API Credential Management: The Complete Guide

Quick answer: API credential management is the practice of controlling how API keys, OAuth tokens, and service credentials are stored, scoped, used, audited, and revoked across your systems. Done well, it means every credential is held in one place, every access is logged, every scope is as narrow as the task requires, and any credential or identity can be cut off in seconds without touching anything else. Done poorly, it means shared keys across services, unknown blast radii, and a revocation process that breaks half your infrastructure.

If your systems include AI agents — coding assistants, autonomous pipelines, background automation — the stakes are higher than for traditional application credentials. Agents don't authenticate with MFA, can't notice when something looks wrong, and often run around the clock without a human watching. The controls have to be structural.

This guide covers the full credential lifecycle, the four storage patterns and their tradeoffs, the scoping model, the rotation-vs-revocation question, audit logging, and how to choose between the major tooling options.

The credential lifecycle

Every API credential moves through five phases. Skipping any one of them is where the problems start.

1. Provisioning

Provisioning is when you create a credential and associate it with an identity. For a human developer, this means generating an API key in a dashboard and putting it somewhere the developer can use it. For an agent or service, it means generating a credential scoped specifically to that agent's access profile and storing it in a vault — not in the agent's environment directly.

The key discipline at provisioning time: every credential should have a clear owner (a specific agent, service, or developer), a defined scope (which services, which actions), and a defined lifecycle (when it expires or when it should be reviewed). Credentials provisioned without these three properties tend to accumulate, spread, and outlast their original purpose.

2. Storage

Where the credential lives between provisioning and use. Covered in detail in the next section.

3. Access

When an agent or service actually uses a credential to make an API call. The access phase is where most logging should happen — not "this credential was created on date X" but "at 2:34am on Tuesday, agent codex-prod retrieved a Stripe read credential and made a customer lookup against customer ID 8821."

Access should be mediated: the agent shouldn't hold the raw credential in memory for the duration of its session. It should request the credential from a broker when it needs it, use it for the specific call, and not cache it longer than necessary. This limits the exposure window if the agent process is compromised or its memory is dumped.

4. Rotation and revocation

Dealt with in detail later in this guide — these are different operations addressing different situations, and conflating them is one of the most common credential management mistakes.

5. Decommissioning

When an agent, service, or developer's access should end permanently. This is different from revocation, which is a response to an incident. Decommissioning is the routine end of an access lifecycle: the agent has been deprecated, the service has been replaced, the developer has left the team.

At decommissioning, every credential and access profile associated with that identity should be audited and closed. Not just the primary key — any secondary keys, OAuth grants, or scoped tokens that were provisioned for that identity during its lifetime.

Storage: the four patterns

Where you store credentials determines their blast radius if something goes wrong. The options from worst to best:

Hardcoded credentials

A key in a .env file committed to a repository. A secret baked into a Docker image. A token pasted into a config file that gets synced across developer machines.

Hardcoded credentials have an unknown blast radius because you can't enumerate every place the key has been copied. Once a credential appears in a git repository — even briefly, even in a branch that was deleted — it should be treated as compromised. Git history persists indefinitely; secret scanning tools check every commit, not just the current HEAD.

The problem isn't just repositories. Hardcoded credentials in MCP config files get synced to every machine that uses the config. Credentials in .env files get copied when developers onboard teammates. Credentials in deployment scripts get included in CI logs. See secret scanning for AI codebases for what scanning catches and what it misses.

For agents specifically, the MCP config file is the current problem vector. Developers adding tools to Cursor, Claude Code, or Windsurf often drop full-access API keys directly into the config — see MCP config file security for the specific risks and the fix.

Verdict: Never store raw service credentials in files that leave the secure boundary.

Environment variables

Better than hardcoded credentials in code, but not secure by design. Environment variables are readable by any process with access to the environment — which, for an agent running in your development environment, means the agent. An env var that's accessible to your application is accessible to any subprocess that application spawns, including any code the agent executes.

The specific risk for agents: a STRIPESECRETKEY in your shell environment gives a coding assistant full Stripe access — not because you granted it, but because it inherits the environment. This is covered in detail in environment variables and AI agents.

Environment variables are acceptable for non-sensitive configuration (feature flags, service endpoints, environment names). They're not an appropriate long-term home for credentials that grant meaningful access.

Verdict: Acceptable as a temporary bridge; not a credential management strategy.

Secrets managers

Dedicated services for storing and retrieving credentials securely. The major options are HashiCorp Vault, AWS Secrets Manager, and Doppler. Each provides:

Secrets managers are the right foundation for application-level credential storage. The limitation for AI agent use cases is that they're designed around what can retrieve a secret, not which agent instance and for what task. A secrets manager will tell you that your deployment pipeline retrieved a database password at 3pm. It won't tell you which of your five Cursor agents retrieved a Stripe key at 2am and what it did with it.

See the tool comparison section below for specifics on Vault, AWS Secrets Manager, and Doppler.

Verdict: Right foundation for storage; may need an agent-specific access layer on top.

Credential brokers with per-agent access profiles

The model that addresses the agent-specific gap. Instead of the agent retrieving a raw credential from a vault, the agent authenticates against a broker with its identity token. The broker checks the access policy for that identity, and if the request is permitted, returns a scoped, short-lived credential for the specific service and operation requested — not the underlying key.

This separation has three properties that matter for agents:

Per-agent auditability. The audit log records the agent's identity alongside the credential access, not just the fact that some process with vault access made a request.

Scope enforcement at runtime. A Cursor agent with a profile scoped to "Stripe read: customer lookup" cannot request a Stripe write credential through the broker, even if the underlying Stripe key has full access. The policy is enforced at the access layer, not at the storage layer.

Independent revocation. Revoking an agent's access profile cuts that agent off immediately without touching the underlying key or any other agent's access. The Stripe key stays live; every other agent with a different profile keeps running.

Verdict: The right model when you have agents making credential-mediated API calls.

Scoping: the least-privilege question

Every credential should carry only the permissions the task it's used for actually requires. Not "read access to Stripe" — "can retrieve customer records and create portal sessions; cannot issue refunds, update subscriptions, or read financial reports."

This is the principle of least privilege, applied to API credentials. The full framing is covered in least privilege for AI agents; the practical version here is: start from the task and work backwards to the minimum permission set, rather than starting from what the service allows and restricting down.

The three dimensions of scope

Service scope. Which external APIs and services can this credential be used with? A coding agent working on a React frontend shouldn't have credentials for your payment processor. An analytics agent shouldn't have write access to your production database.

Action scope. Within a service, which operations are permitted? An agent that needs to look up Stripe customer records for display doesn't need to create charges, issue refunds, or update payment methods. Read and write access to the same service should be separate credentials issued against separate access profiles.

Data scope. Within an operation, which records or environments? An agent working in a staging environment shouldn't have credentials that reach production. An agent scoped to one customer account shouldn't be able to enumerate all customer records.

For a detailed worked example mapping these three dimensions to a real agent setup, see AI agent permissions.

Over-scoped credentials compound over time

The failure mode isn't usually a single agent with dangerously broad access. It's five agents, each individually "not that risky," that collectively have full read-write access to every system in the stack. When something goes wrong — a runaway loop, a prompt injection, a compromised environment — you discover that every agent has a blast radius that extends further than anyone intended.

Scoping is easiest to enforce at provisioning time. Expanding a scope is straightforward; auditing and tightening a scope that has been in production for months, across agents that are actively running, is much harder. See identity and access management for AI agents for the full framing of why the IAM discipline transfers — and where it needs adjustment — when the identities are agents.

Rotation vs. revocation

These are different operations, used in different situations. Using the wrong one wastes time, breaks things, or leaves exposure in place.

The full comparison is in API key rotation vs. revocation. The summary:

Rotation replaces the credential itself — the old key is invalidated, a new key is issued, and every system that depends on the old key needs to be updated. Rotation is the right response when the credential itself may be compromised: it appeared in a log, it was included in a conversation, it was exposed in a breach.

Rotation is the wrong default for agents because it affects every system using that credential, not just the one that had the problem. If five services share a database credential and one service's agent behaves unexpectedly, rotating the database credential breaks all five — a broad disruption to address a narrow problem.

Revocation cuts off access for a specific identity without touching the underlying credential. If your agents authenticate through access profiles rather than holding raw keys, revoking a profile is the right response to a compromised or misbehaving agent: the agent loses access instantly, the underlying key is unchanged, and every other agent and service keeps running.

The practical implication: prefer a model where agents hold access profiles rather than raw credentials, so that revocation is available as an option when something goes wrong. When agents hold raw keys, the only available response is rotation — which is slower, broader, and more disruptive.

Expiry as a complement to revocation

Short-lived credentials that expire automatically are a complementary control. If a credential is only valid for 15 minutes, a compromised agent's window of continued access is bounded even if you haven't yet noticed the problem and issued a revocation. HashiCorp Vault's dynamic secrets model does this for infrastructure credentials; the same pattern applies at the agent access layer.

Audit logging

Audit logs are the evidence layer. They're what you look at when a billing anomaly appears, when a customer reports unexpected activity, or when a security review asks for evidence that access to production systems was controlled.

For API credential management, there are two distinct logging layers:

Credential retrieval logs

What was retrieved, by whom, when, and from which system. This is what most secrets managers provide: "the deployment pipeline retrieved the database credential at 14:32 on July 15."

This layer is necessary but not sufficient for agents. Knowing that a credential was retrieved doesn't tell you what it was used for.

Usage logs

What API calls were made using the credential, by which agent, against which resources. This requires either per-agent credentials (so usage can be attributed to a specific identity) or a proxy layer that intercepts and logs calls.

For the IAM question — which identity did what, when, with what authorization — usage logs are what auditors actually need. SOC 2 CC6 (logical access controls) doesn't just require that access was controlled; it requires evidence that access was controlled and that the access that occurred was authorized. Usage logs at the agent level are that evidence.

What to log

At minimum, for every agent credential access:

Aggregate this by agent over time and you can answer "what did this agent actually do last Tuesday?" — which is the question that matters when something looks wrong.

Retention

Log retention requirements vary by compliance framework. For SOC 2 Type II, auditors typically want evidence covering the audit period (usually 12 months). For GDPR incident response, 72-hour notification timelines mean you need logs accessible immediately, not archived. Keep access logs for at least 12 months; keep the most recent 90 days immediately queryable.

The AI agent dimension

Everything above applies to credential management for humans, services, and infrastructure. Agents introduce specific complications that the traditional model doesn't account for:

Agents don't fail safely

A human developer who encounters an unexpected permission error notices it, stops, and asks for help. An agent in an autonomous loop often retries, tries a different approach, or escalates — sometimes accumulating errors and side effects before anything raises a flag. Credentials that are too broad give the agent more surface area over which to cause unintended damage during a failure mode.

This is why scope enforcement needs to be structural: the agent should be unable to take a high-risk action, not just expected not to. An agent that can't issue refunds because its access profile doesn't include that permission is safer than an agent that has refund access but has been instructed not to use it.

Agents can be injected

Prompt injection — malicious instructions in content the agent reads, rather than in its direct prompt — is a live attack class for any agent that processes external content. An agent that reads files, fetches URLs, or processes API responses can be redirected by content in that data. See what happens when you paste an API key into an agent's prompt for a related framing of how credentials end up in unexpected places.

Scoped credentials limit the blast radius of a successful injection: even if the agent is redirected, it can only take actions within its permitted scope. This is defence-in-depth, not a full defence — but it meaningfully reduces the cost of a successful attack.

Multi-agent systems multiply the surface area

When agents spawn or call other agents — an orchestrator dispatching sub-agents for subtasks — the credential question becomes: how do credentials propagate through the pipeline?

The wrong model: the orchestrator passes its own full credentials to each sub-agent. This gives every sub-agent in the chain the orchestrator's full access, which means the blast radius of a compromised sub-agent extends to everything the orchestrator can touch.

The right model: each agent in the pipeline has its own access profile, scoped to its specific task. The orchestrator passes task context, not credentials. Sub-agents authenticate independently against the broker with their own identities. See multi-agent credential management for the full pattern.

Tool comparison

The major tools occupy different layers of the credential management stack. They're not all solving the same problem, and several of them compose naturally.

HashiCorp Vault

Vault is an infrastructure-grade secret storage system. It excels at dynamic secrets (credentials generated on demand and automatically expired), broad integrations with cloud platforms and databases, fine-grained access policies, and self-hosted deployment with strong audit capabilities.

The limitation for AI agents: Vault's access model is designed for applications and infrastructure, not for agent identities. It doesn't natively support per-agent access profiles, agent-level audit trails at the individual session level, or approval gates on high-risk agent actions. It's a strong backing store; you may need an agent-specific access layer on top.

See HashiCorp Vault vs. Gazebo for a full comparison of where each fits.

AWS Secrets Manager

AWS Secrets Manager is tightly integrated with AWS IAM, making it the natural choice for teams already on AWS. IAM roles provide automatic rotation, fine-grained resource policies, and clean integration with ECS, Lambda, and EKS workloads.

The limitation: IAM roles are designed for AWS-native workloads. Agents that need credentials for Stripe, GitHub, Vercel, or other services outside the AWS boundary need a different model — IAM doesn't issue credentials for non-AWS services. And the audit trail is at the IAM identity level, not the individual agent session level.

See AWS Secrets Manager for AI agent workflows for the full comparison.

Doppler

Doppler is a developer-friendly secrets manager focused on syncing credentials across environments, teams, and CI pipelines. It solves the problem of secrets in .env files and manual credential distribution. Its audit logs cover secret changes and access at the config/environment level.

The limitation for agents: Doppler scopes access at the config level, not the agent identity level — every service pulling from a config gets the same secrets. You can create a separate config per agent to approximate per-agent isolation, but it's manual overhead rather than a built-in identity model. There are no approval gates before agent execution (Doppler's Change Requests feature governs secret value updates, not agent actions). And access logs show the first and most recent time a service token accessed a secret — not a full per-request audit trail at the individual agent session level.

See Doppler vs. Gazebo for the full comparison.

Gazebo

Gazebo is designed specifically for the agent-facing access layer: per-agent access profiles, per-request audit logging at the individual agent identity level, approval gates on high-risk actions, and revocation that cuts one agent's access without touching anything else.

It can sit in front of the tools above — Vault or AWS Secrets Manager holds the underlying credentials, Gazebo enforces per-agent policies on top and issues scoped tokens through an MCP endpoint. Or it can be used standalone for teams building agent-first infrastructure. See Gazebo's security model for how the layers fit together.

Choosing between them

Traditional app deployments, no agents: Doppler or AWS Secrets Manager handles the credential distribution problem cleanly. Start here.

Infrastructure-heavy or self-hosted: HashiCorp Vault gives the most control. Pair with per-agent profiles at the access layer if you're adding agents.

AWS-native with IAM roles: AWS Secrets Manager for AWS-boundary credentials; an agent access layer for anything that leaves the AWS boundary.

Agent-first or adding agents to an existing stack: Gazebo as the agent access layer, backed by whatever vault you're already using — or standalone if you're starting fresh.

Getting started

If you're building a credential management foundation from scratch or auditing an existing setup:

1. Inventory what you have. Which credentials exist, where are they stored, which services use them, and which agents have access? Hardcoded credentials and shared keys surface here.

2. Centralise storage. Move credentials out of code, config files, and .env files into a secrets manager. This is the baseline.

3. Define access profiles. For each agent, define the minimum service and action scope its task requires. Not "API access" — "Stripe: read customers; GitHub: create PRs on repo X."

4. Instrument access. Ensure every credential retrieval is logged against an identity, not just a service account.

5. Test revocation. Before you have a crisis, verify that you can revoke one agent's access profile without taking down other services. If revocation requires rotating a shared key, that's the gap to close.

6. Review quarterly. Agents accumulate access that outlasts their original purpose. A quarterly review of which agents have access to which services — and whether that access is still needed — prevents scope creep from compounding.

Comparison last reviewed: August 2026. Check each tool's current documentation for the latest feature set. This is an independent editorial overview — not affiliated with or endorsed by HashiCorp, Amazon Web Services, or Doppler.