Quick answer: API credential management is the lifecycle of knowing which credentials exist, who owns them, what they authorise, how consumers obtain them, and how they are replaced or invalidated. A useful inventory separates provider permissions from the controls governing credential retrieval.
This guide covers credentials across applications, services, people and automation. For agent onboarding and offboarding responsibilities, use the agent-specific operating lifecycle. For the trust boundaries underneath delivery, see the secrets architecture guide.
1. Inventory credentials and consumers
Start with a non-secret record for each credential:
- Issuer, service and intended environment.
- Owner and business purpose.
- Provider permissions and restricted resources.
- Storage location or reference—not the secret value.
- Known consumers and how each authenticates to retrieve it.
- Expiry, review date and replacement procedure.
- Where retrieval and provider activity are recorded.
A vault can tell you which values it stores, but not necessarily every place a previously retrieved key has been copied. Validate the inventory with service owners, runtime configuration and available provider records.
2. Issue permissions at the right layer
Create restricted provider credentials where supported. Check operation, resource and environment boundaries rather than using a broad administration key for convenience.
A distribution policy is separate. It controls whether a consumer can retrieve a stored key, not what the key authorises after delivery. If the provider cannot express a required restriction, a retrieval-policy label cannot supply it. You may need a different provider interface, a smaller workload trust boundary or a request-executing proxy.
Provider-issued temporary credentials can reduce the lifetime of exposed copies. They require an appropriate issuer and integration; placing a static key in a broker does not make it temporary.
3. Choose storage and delivery for the workload
Avoid committing secrets to source or distributing them through chat. Use a protected store with suitable authentication, access controls, key management and recovery procedures.
Delivery options have different tradeoffs:
| Pattern | Useful property | Boundary to inspect |
|---|---|---|
| Environment injection | Compatible with many applications | Which process and children inherit the value, and where diagnostics may reveal it |
| Mounted secret or rendered file | Can separate configuration from source | File permissions, readers, backups and reload behaviour |
| Authenticated runtime retrieval | Central retrieval policy and records | Bootstrap authentication, service availability and handling of returned plaintext |
| Provider-issued temporary credentials | Issuer-enforced scope and lifetime | Supported workloads, renewal and actual invalidation semantics |
| Request proxy | Can keep provider keys away from consumers | Forwarding rules, bypass routes and the proxy's own permissions and availability |
These are not a universal ranking. A workload with existing identity and secrets infrastructure may already have an appropriate delivery path. Protecting a stored value does not remove the need to trust an authorised consumer.
4. Authenticate each independently managed consumer
Use workload identities or appropriately protected tokens to distinguish consumers that need different access or offboarding decisions. Avoid a single shared retrieval identity when it prevents meaningful attribution.
In Gazebo, agents authenticate with an agent token or authorised OAuth connection. Gazebo checks retrieval policy and returns the actual stored provider credential to the runtime and its host. OAuth connections require approval of the stored key names. The declared-method check is release-policy context, not downstream request enforcement.
Review how the client handles returned values. Runtime retrieval is not a guarantee that a key stays outside model context, traces or conversation history.
5. Record retrieval and usage separately
Retrieval evidence identifies the consumer requesting a credential, the requested key and the release outcome.
Usage evidence comes from provider or runtime records describing actual operations, resources and results. One retrieval can support many later requests. If several consumers share a provider key, downstream attribution may require additional evidence.
Keep secret values out of both layers. Document actual coverage and retention rather than promising that one log answers every incident question. Set retention according to security needs, applicable obligations and data-minimisation requirements; there is no single universal period for all credentials.
6. Replace and invalidate deliberately
Separate retrieval-access revocation, provider-key revocation and key replacement. Removing a consumer's retrieval permission does not invalidate its retained provider key.
For routine replacement, identify consumers, use an overlap period if supported, verify the new credential, then retire the old one. During compromise, prioritise containment rather than preserving an exposed key for a convenient cutover.
At decommissioning, close unnecessary retrieval access, retire runtimes and invalidate dedicated provider keys when continued use should end. See rotation versus revocation for a response table.
Choosing tooling
Existing secrets managers can support machine identities, policies and audit records. Depending on the product and configuration, they may also offer dynamic credentials, rotation integrations and workload-native authentication.
HashiCorp Vault, AWS Secrets Manager and Doppler have different deployment and integration models. Evaluate current documentation against your workloads rather than assuming they cannot distinguish agents. A dedicated agent-facing layer should prove that it reduces integration or review effort.
Gazebo brings together named agent identities, selected-key OAuth approval, retrieval policies and credential-access history, with SDK, CLI, API and MCP integration paths. It does not automatically narrow provider keys, issue temporary replacements, approve downstream operations or log provider traffic.
The practical success measure is whether you can identify an owner, verify permissions, explain a delivery event and end unwanted access at both the retrieval and provider layers—not how many security products are in the path.