Quick answer: Secrets management for AI agents combines protected credential storage, caller authentication, retrieval policies, runtime handling and provider permissions. These are separate controls. A system that checks whether an agent may retrieve a key does not necessarily hide that key from the runtime or control the API calls made afterward.
This is the reference guide to the architecture. For actions you can verify in an existing deployment, use the six-practice operating checklist. For ownership, onboarding and offboarding, read the credential-management lifecycle.
What counts as a secret?
API keys, OAuth access and refresh tokens, database passwords, connection strings and webhook signing secrets all need protection. An environment variable is a delivery mechanism, not a different class of credential: its value may still grant sensitive access.
Record what each secret can do at its issuer. A read-only token for one repository and an organisation-wide administration key have different consequences if exposed, even when both are stored in the same encrypted vault.
The five boundaries in the architecture
1. Storage: where the credential lives
A vault protects stored values and controls access to them. Evaluate encryption, key management, backup handling, administrator access and recovery procedures. Encryption at rest does not mean an authorised consumer never receives plaintext.
Keep the agent's bootstrap authentication separate from its provider credentials. Moving a provider key into a vault still leaves a question to solve: how does the runtime prove it may retrieve that value?
2. Authentication: which caller is requesting access
Give independently managed agents distinct identities. A runtime might authenticate through a workload identity, a scoped token or an authorised OAuth connection, depending on the system.
Established secrets infrastructure can support machine authentication and narrow policies. For example, Vault's AppRole authentication is intended for machines and applications. The question is whether your integration maps those identities to the agents and environments you need to manage.
3. Retrieval policy: which key may be released
The retrieval layer maps a caller to permitted services and credentials. It can deny a request before releasing a key and record the outcome.
Gazebo checks an agent's credential-retrieval policy. In OAuth connections, the user explicitly approves the stored key names the client may retrieve. Gazebo also checks the declared method against its release policy. That method is supplied as policy context; Gazebo does not inspect a subsequent provider request or transform a broad key into a read-only one.
4. Runtime handling: who receives the value
Once a stored credential is returned, the runtime and its host receive the actual value. Whether it also enters model context, tool traces, conversation history or diagnostic logs depends on the client.
Avoid deliberately putting keys into prompts, redact sensitive tool results where the integration permits it, and review the host's handling of credentials. Runtime retrieval reduces the need to distribute keys manually; it is not a guarantee that the key remains outside the model's context.
5. Provider permissions: what the key can do
The provider ultimately decides which direct API requests a retrieved key authorises. Configure restricted resources, operations, expiry and other available controls at the provider.
If a runtime receives a write-capable key, declaring GET during retrieval does not prevent later writes with that key. Where the provider cannot express the restriction you need, a request proxy may be worth evaluating rather than assuming the retrieval policy supplies it.
Three credential-delivery models
| Model | What the runtime receives | Where later use is controlled | Revocation boundary |
|---|---|---|---|
| Stored-key retrieval | The configured provider credential | Provider permissions and runtime controls | Denying retrieval stops new delivery; existing copies remain valid until provider expiry or revocation |
| Provider-issued temporary credentials | A credential with provider-enforced scope and lifetime | Provider permissions, expiry and supported revocation mechanisms | Exact behaviour depends on the provider; a lease or expiry must not be assumed to cancel completed actions |
| Request proxy | An interface for requesting operations, without the provider key being returned | Proxy rules on forwarded requests, plus provider permissions | Can deny future forwarded requests, but cannot undo completed operations or control traffic that bypasses it |
A credential-release broker checks who may retrieve a stored key. The authorised runtime receives that key, and provider permissions govern its subsequent use. A request proxy instead keeps the provider key inside the proxy and checks the requests it forwards. These are different security boundaries; Gazebo currently provides credential retrieval.
Temporary credentials are not an automatic property of using a broker. A system needs a supported issuer and integration to create them. Likewise, a proxy needs endpoint-specific rules, safe forwarding and appropriate provider credentials; the name alone does not establish those controls.
Evidence: retrieval logs are not provider activity logs
A retrieval record can establish which authenticated agent requested which credential, when, and whether release succeeded or was denied. It does not establish whether the agent then read a customer, created a charge or made no provider call at all.
Use provider and runtime records for those questions. A single retrieved key may support many API calls, and shared provider keys can limit attribution even when retrieval identities are distinct.
For incidents, distinguish three actions: disable future retrieval, stop or isolate the runtime, and invalidate a potentially exposed provider credential. They address different parts of the architecture. See rotation versus revocation for the operational tradeoffs.
Evaluating an implementation
Ask for a concrete walkthrough rather than a list of security labels:
- How does a new runtime authenticate without embedding a provider key?
- Can it retrieve only the named credentials it needs?
- Which system limits the provider operations those credentials permit?
- Where can returned values be retained or logged?
- What does revocation stop, and what continues with an already-delivered key?
- Which logs establish retrieval, and which establish downstream activity?
General-purpose secrets managers may already meet these requirements through workload authentication, policies and integrations. Gazebo's potential advantage is a focused workflow for connecting agent clients, approving credential retrieval and reviewing access across services—not a fundamentally different property of encryption.
For Gazebo's current retrieval interface, start with MCP or the SDK, and review the security overview. Use the operating checklist to verify the controls after setup.