Skip to main content
A Credential is a sensitive value stored in a vault that Agent Vault attaches to proxied requests. This can be an API key, database credential, password, OAuth token, or any other sensitive material. Each credential has:
  • Key: An UPPER_SNAKE_CASE name (e.g. STRIPE_KEY, GITHUB_TOKEN) for the credential. This is used to reference the credential in services.
  • Type: Either static (default) or oauth. Static credentials are simple encrypted values. OAuth credentials store access and refresh tokens with automatic token refresh.
  • Value: The credential material, encrypted at rest with AES-256-GCM. Values are only decrypted in memory at proxy time.
Credentials can be referenced in vault services by key name. When an agent makes a proxied request, Agent Vault resolves the key to the real credential value and attaches it to the outbound request.
Credential values are encrypted at rest and only decrypted in memory when needed. Vault members and admins can read credential values via vault credential get or vault credential list --reveal. Agents with the proxy role cannot read credential values — they are only injected at proxy time.
Credentials can be added to a vault in two ways:
  • Automatically: When an agent needs access to a new service, it can raise a proposal that includes the credential slots it needs. You review the proposal, provide the credential values, and approve. This is the recommended workflow for working with Agent Vault.
  • Manually: You can set credentials directly via the CLI before inviting agents. This is useful for pre-configuring a vault with known service credentials.
Vaults backed by an external credential store (e.g., Infisical) are read-only from Agent Vault; manage their credentials upstream instead.

​
OAuth credentials

OAuth credentials let Agent Vault manage OAuth 2.0 tokens that are automatically refreshed when they expire. The proxy injects the access token as a Bearer header, just like a static credential, but handles the refresh lifecycle transparently. There are two ways to set up an OAuth credential:

​
Connect with provider

You register an OAuth app with the provider (e.g., GitHub, Google), enter the client ID and secret in Agent Vault, and click “Connect.” Agent Vault handles the browser redirect, consent flow, and token exchange using Authorization Code + PKCE. The URL fields suggest popular providers (GitHub, Google, Slack, Microsoft, and others) as you type; picking one prefills the authorization URL, token URL, and token auth method. Any other provider works too: just paste its URLs directly. The scopes field shows provider-specific suggestions when a provider is selected; you can also type custom scopes. After connecting, Agent Vault stores the access token, refresh token, and expiry. When the access token nears expiry (within 5 minutes), the proxy automatically refreshes it before injecting.

​
Paste tokens

If you already have OAuth tokens (e.g., from a CLI tool like Claude Code), you can paste them directly. If you provide a refresh token, Agent Vault validates it immediately by performing a refresh against the provider’s token endpoint. If the refresh fails, the upload is rejected. This mode is useful for:
  • Tokens obtained from CLI tools with localhost-only OAuth flows
  • Tokens from IT/admin that were pre-provisioned
  • Migrating tokens from another system
OAuth credentials appear in the credentials list with type OAuth. The proxy injects them identically to static credentials — services reference them by key name and don’t need to know the credential is OAuth-managed.

​
Store a credential

agent-vault vault credential set STRIPE_KEY=sk_test_abc123 --vault my-vault
The vault credential command (alias: vault creds) uses KEY=VALUE format. Multiple credentials can be set at once (e.g. agent-vault vault credential set A=1 B=2). If STRIPE_KEY already exists, it is overwritten.

​
Delete a credential

agent-vault vault credential delete STRIPE_KEY --vault my-vault
Permanently removes the credential from the vault.
Every credential key referenced in a vault service must resolve to either an existing credential or a credential slot in the same proposal. If you delete a credential that is still referenced by a service, proxy requests to that service will fail with a 502 error.
Agents can propose new credentials through proposals without ever handling the actual values. There are two flows:Agent needs a credential from you: The agent creates a proposal with a credential slot (key name, description, and optionally an obtain URL with instructions). You receive a browser link, enter the value, and click “Allow”. The credential is stored encrypted on approval.
{
  "credentials": [{
    "action": "set",
    "key": "STRIPE_KEY",
    "description": "Stripe API key",
    "obtain": "https://dashboard.stripe.com/apikeys",
    "obtain_instructions": "Developers > API Keys > Reveal test key"
  }]
}
Agent generated a credential: If the agent created an API key or received a token during a workflow, it can include the value field in the proposal. You review the proposal and confirm the value is correct before it is stored.
{
  "credentials": [{
    "action": "set",
    "key": "GENERATED_TOKEN",
    "description": "Token generated during setup",
    "value": "tok_abc123"
  }]
}
Each credential slot has an action field: set (add or replace) or delete (remove). Approval atomically applies all credential changes in a single transaction.
Agents can propose OAuth credentials by setting type: "oauth" and including an oauth config object with the provider’s token URL. The authorization_url determines the mode: if present, the approval page shows a “Connect” button; if omitted, it shows token paste fields.
{
  "credentials": [{
    "action": "set",
    "key": "GITHUB",
    "type": "oauth",
    "description": "GitHub OAuth",
    "oauth": {
      "authorization_url": "https://github.com/login/oauth/authorize",
      "token_url": "https://github.com/login/oauth/access_token",
      "scopes": "repo user"
    },
    "obtain_instructions": "Register an OAuth app at github.com/settings/developers"
  }]
}
When you approve, no credential value is required for OAuth slots. You complete the connection by entering client credentials and clicking Connect (or pasting tokens) on the approval page.
Agents can also propose removing credentials they no longer need:
{
  "credentials": [{ "action": "delete", "key": "OLD_API_KEY" }],
  "message": "Remove unused API key"
}
Delete-action slots only require the key field. The credential is removed when you approve the proposal.