> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Credentials & secrets
> Store a secret once, bind it to the agents allowed to use it, and have it delivered to runs without its value ever being exposed.
Agents need secrets, and the wrong answer is to bake them into an image or a config file. The
Komodor Agentic Operation Platform (KAOP) stores a secret once, encrypted, records which agents are
allowed to use it, and delivers it into a run without ever revealing the value — to you, to the
agent's logs, or to its evidence trail. This page covers creating a credential, binding it, how a run
receives it, and how rotation works.
## The model in one paragraph
A **credential** is a named, encrypted secret. It is **write-only**: once stored, the value can be
replaced or deleted but never read back. A **binding** records that a specific agent may receive a
specific credential. At run time KAOP resolves the agent's bindings, decrypts the values, and hands
them to the run in memory. Nothing about the value is written to the run's evidence, and any
occurrence of it in output or logs is masked before it leaves the worker.
Find them under **Credentials**.
## Create a credential
Press **New credential**.
Letters, digits, dashes, and underscores. This is the name agents bind to and the name your code
resolves, so pick something stable — renaming later means updating what reads it.
**Single value** for a plain secret string. **Multiple keys** for a named set of key-value pairs,
such as an OAuth client id and secret that belong together.
A single-value credential takes one secret. A multi-key credential can be filled as key-value
rows, pasted as JSON, or uploaded as a `.json` or `.env` file.
**Description** and **Owner** are how a person six months from now knows what this is and who is
accountable. **Labels** are key/value metadata, and they can control who may see the credential.
The bindings step is where you choose which agents may use it. You can also do this later.
If you create a credential whose value your workspace already holds, KAOP recognizes it and returns
the existing credential rather than storing a second copy — under whatever name that credential
already has. This is deliberate: one secret, one row, one place to rotate it.
## Bind it to agents
A stored credential reaches nothing until it is bound. A binding is per-agent and explicit — there is
no "all agents" setting, which is what makes the question "who can use this secret?" answerable.
From the credential's access view you can see every agent bound to it, grant access to another, and
remove one. From an agent's own **Permissions** and secrets view you can do the same from the other
direction. Changes there take effect immediately, per action.
### Narrowing a multi-key credential
A multi-key credential can be bound with **key restrictions**, so an agent receives only the keys it
needs rather than the whole set. An agent with no restriction receives every key.
Use key restrictions rather than splitting one logical credential into several. A Google Workspace
OAuth credential should stay one credential; the agent that only needs the client id gets only the
client id.
### Delivery timing
| Binding | When the value arrives |
| ------------- | ------------------------------------------------------- |
| Default | With each run |
| **On-demand** | Also available to the worker outside a run, at start-up |
On-demand is for a token a worker needs before it can do anything at all — a connection it must
establish while booting. Use the default unless the worker genuinely cannot wait for a run.
## How a run receives it
Values are handed to the run in memory. In an agent you author, the SDK reads them from the run's
context:
```python theme={null}
from komodor_agentops import get_secret, get_secret_key, get_secret_dict
# A single-value credential, by its name.
api_key = get_secret("DATADOG_API_KEY")
# One key of a multi-key credential.
client_id = get_secret_key("google-workspace-oauth", "client_id")
# Every key of a multi-key credential.
oauth = get_secret_dict("google-workspace-oauth")
```
If a library you use expects an environment variable, put it there for the life of the handler:
```python theme={null}
from komodor_agentops import apply_secret_to_env
apply_secret_to_env("ANTHROPIC_API_KEY")
```
Secrets are **run-scoped**. They are set before your handler is called and cleared when it returns,
so a worker holding several concurrent runs cannot read one run's secrets from another's context.
Read them inside the handler, not at import time.
A multi-key credential expands into the environment as one variable per key, named
`CREDENTIAL_NAME__KEY` — so the `client_id` key of `google-workspace-oauth` becomes
`GOOGLE_WORKSPACE_OAUTH__CLIENT_ID`. The bare credential name is not set for a multi-key credential.
## What is never exposed
This is the guarantee worth understanding precisely, because a lot of the design follows from it.
* **The value cannot be read back.** No API returns it. Metadata — name, description, owner, status,
labels, active version, when the value was last replaced, when it was last used, and for a
multi-key credential the *names* of its keys — is all that any read returns.
* **Values are masked on the way out.** Every delivered value is redacted from the run's output,
snapshots, diagnostics, error messages, and telemetry as they are emitted. Longer values are masked
before any value they happen to contain, so a substring cannot leak past the mask.
* **Chat and tools cannot create one or see one.** The console's create form posts the value directly
and no assistant-drivable surface has a field for it. What an assistant can do is bind or unbind an
existing credential by name.
* **Encryption at rest is envelope encryption**: a fresh data key per value, AES-256-GCM for the
payload, and that key wrapped under a deployment master key. Only the control plane's decrypt
boundary ever sees plaintext.
The knowledge base, an agent's instructions, and a skill's content are *not* secret. They are
readable by anyone who can read the agent. Anything that must stay secret belongs in a credential.
## Rotate a value
Rotation is **Replace value**. It stores a new active version; the previous version stops being
delivered.
From the credential's row. The name, bindings, and labels are untouched — which is the point:
nothing that references the credential needs to change.
If a multi-key replacement no longer contains a key some binding was restricted to, that
restriction is trimmed and the response says which bindings changed. Read it.
The new value is delivered from the next run. A worker holding a value from boot needs a restart.
There is no separate rotate action and no rotation schedule to configure. Replacing the value *is*
the rotation, and because the credential's name and bindings survive it, rotating is safe to do as
often as your policy requires.
## Disable and delete
| Action | Effect |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Disable** | The credential stops being delivered to runs, but is kept. Use it to test whether something still depends on a secret before removing it |
| **Delete** | Permanent. Agent bindings go with it |
Deleting is refused while something structural still points at the credential — an MCP server bound
to it, or a static header referencing it by name. The refusal names what depends on it. Repoint or
remove those first.
Disable before you delete. A disabled credential produces a clear, attributable failure in whatever
still needs it, which is a far better way to find the dependency than a deletion you cannot undo.
## Where a credential shows up
The same store serves everything that needs a secret, which is why there is only one place to rotate:
| Consumer | How it uses the credential |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| An agent | Bound to the agent, delivered per run or at boot |
| A [built-in integration](/manage-your-agents/build/built-in-integrations) | Holds the provider's credentials for the connection |
| An [MCP Gateway](/manage-your-agents/build/mcp-gateway) server | Bound to the server, injected on each call, or referenced from a static header |
A credential's usages view lists all three, which is what to check before changing or removing one.
## Reserved names
KAOP provisions a few credentials for your workspace itself — the ones behind the managed model
gateway. Those names are reserved, and creating your own credential under one of them is refused.
They appear in your list, owned by the platform, and you do not manage them.
## Next steps
Where most credentials end up being created.
Referencing a credential from your own tool server.
The full security architecture behind this page.
Resolving a credential inside your handler.
## Related topics
- [Secrets & credential handling](/security-and-governance/architecture-considerations/secrets-credential-handling.md)
- [Integrations overview](/manage-your-agents/build/integrations-overview.md)
- [Build from scratch](/manage-your-agents/build/build-from-scratch.md)
- [Manage a deployed agent](/manage-your-agents/build/manage-a-deployed-agent.md)
- [Configuration clusters](/security-and-governance/identity-and-access/configuration-clusters.md)