Token Vault

The Kong Identity Token Vault is a Konnect built-in credential broker. It stores your users’ credentials for third-party upstream services (for example, GitHub, Slack, or Workday) and releases them to Kong AI Gateway so agents can call those protected services on a user’s behalf, without the agent ever holding the credential itself.

Set up the Kong Identity Token Vault in the following cases:

The following diagram shows how a request flows from a principal to a third-party credential provider through the Kong Identity Token Vault:

1. A principal (your users, agents, and applications) sends a request through AI Gateway.
2. AI Gateway routes the request to an MCP server with a Token Vault provider attached for outbound authentication.
3. Token Vault verifies the caller’s token with the trusted IdP, using the token’s issuer (iss) and subject (sub) to identify the principal.
4. Token Vault releases the matching credential for the credential provider, such as GitHub or Slack. If the principal doesn’t have a credential for that provider yet, AI Gateway returns an enrollment URL so they can connect their account first. See Credential enrollment.

The IdP token only identifies the principal. It never becomes the stored credential.

flowchart LR
    principal["<b>Principal</b><br/>Your users, agents, and applications calling through Kong."]
    gateway["<b>Kong AI Gateway</b><br/>Routes the request to Token Vault."]
    vault["<b>Token Vault</b><br/>Verifies, then releases a credential."]
    idp["<b>Trusted IdP</b><br/>The issuer Token Vault trusts to verify a caller's token."]
    providers["<b>Credential providers</b><br/>GitHub, Slack, and other providers your agents call."]
    principal -->|Request| gateway
    gateway --> vault
    vault -->|Verify| idp
    vault -->|Authorizes| providers

The following table shows what using Token Vault brings to your authentication setup and flows:

Token Vault operates under the following constraints:

• Only the AI Gateway can request credentials from Token Vault, and that connection is locked down over mutual TLS (mTLS): both sides prove their identity with certificates.
• Agents and MCP clients never call Token Vault directly: if an agent needs a credential, it has to go through the AI Gateway.
• Token Vault never queries the corporate IdP about a user. It only fetches the IdP’s public keys (JWKS) to verify that:
  • The token’s signature is valid.
  • The token was issued by the IdP that an admin set as trusted for that directory.

The AI Gateway role

AI Gateway acts as a bridge between the user and the third-party service.

You attach policies to the AI Gateway, which is where you scope and enforce call behaviors. Token Vault doesn’t hold any policies, it only verifies whose token this is and returns the matching credential if one exists. For example, in a workflow configured with Okta as the IdP, the AI Gateway:

1. Receives a caller’s Okta-issued token.
2. Presents it to Token Vault to request a credential for a specific provider.
3. After it gets one back, it injects the credential into the actual outbound request to the third-party service (for example, as a header, for providers that support it).

The Kong Identity directory is the tenant boundary that scopes identities and access in Token Vault. To use Token Vault, you activate it in your directory with the vault_enabled flag.

The directory is also the encryption boundary for Token Vault. After you enable Token Vault on your directory, register a public vault key on it (POST /v2/directories/{directoryId}/vault/keys). The vault key protects the credentials you store. See Credential storage and encryption. Trusted IdPs, providers, and credentials are all scoped to the directory, so no other directory can access them.

The trusted IdP is what tells Token Vault whose tokens to trust. A Kong Identity admin configures a trusted IdP (for example, Okta) on the directory using the issuer_url, and optionally a jwks_uri (Kong Identity can automatically discover the jwks_uri from the IdP). A directory can have more than one trusted IdP, each identified by a unique issuer_url. Token Vault only accepts an IdP’s tokens when you set vault_access_enabled to true on the directory. The trusted IdP can be your corporate IdP, or the Kong Identity authorization server, for example when clients authenticate with an Identity Assertion JWT Authorization Grant (ID-JAG) issued by your corporate IdP.

Token Vault verifies tokens and never queries the IdP about a user directly. When it receives a token, it:

1. Checks that the token’s signature matches the trusted IdP’s published public keys, and confirms the IdP actually issued it. Only asymmetric signing algorithms (RS, PS, and ES families) are accepted.
2. Checks the token’s expiry (exp) and not-before (nbf) claims.
3. Reads the issuer (iss) and subject (sub) already embedded in the token, to determine who it was issued to.

Users don’t need to exist in Kong Identity beforehand. Token Vault supports just-in-time (JIT) provisioning, also called automatic user provisioning, on its identity providers (IdPs). When jit_provisioning_enabled is true (the default) and no Kong Identity principal matches the token’s issuer and subject, Token Vault creates one. Per-user credentials are stored for that principal.

To enable JIT provisioning in the Konnect UI, go to AI > Access Management > Identity Providers, then create a new IdP or edit an existing one, and enable Automatic user provisioning.

To add a trusted IdP, send a POST request to the /v2/directories/{directoryId}/trusted-idps endpoint. The issuer_url must be unique within the directory, so a POST reusing an existing issuer returns a 409. The request accepts the following body parameters:

PUT on /v2/directories/{directoryId}/trusted-idps/{trustedIdpId} replaces the whole configuration, so omitted fields reset to their defaults. Use PATCH to change individual fields.

You connect third-party services by adding a provider to the Kong Identity Token Vault. This lets an organization centralize identities and shared connections in one place, instead of configuring each service separately in every agent or client.

Kong Identity provides templates to bind external services. The template supplies the third-party service’s secret type, default OAuth endpoints, default scopes, and credential placement. To list the templates and their defaults, send a GET request to /v2/credential-provider-templates. You create a provider by sending a POST request to the /v2/directories/{directoryId}/vault/providers endpoint with the following fields:

• template_name: The provider template to bind, listed in the following table.
• name: The custom name for this provider. Use it to tell apart several providers built from the same template. Must be unique in the directory, and match ^[a-zA-Z0-9_-]+$.

The following provider templates are available:

The Kong Identity Token Vault protects the credential, the actual secret (a token or a key) for connecting to a provider. The credential is encrypted at rest in Token Vault. See Credential storage and encryption.

The credentials can be personal or shared across the organization. You define this with the credential_type field on the provider:

• user sets a personal credential, enrolled by each user.
• shared sets a credential shared across the directory, managed by an admin.

The allowed values and default depend on the provider’s secret type:

Credential storage and encryption

Token Vault encrypts every credential before storing it, using a key that you control. Each directory has its own vault key, so one directory can’t read another directory’s credentials.

The following table shows what encrypts what, and what can access each key:

You need to register a vault key because it makes you the owner of the encryption: without the private key, Kong can’t read your credentials. Token Vault doesn’t store any credential until you register one.

A credential’s value never comes back through any API. Read endpoints only return metadata (IDs, timestamps, status). Only the AI Gateway receives a credential, to use in outbound calls.

OAuth-based credential lifecycle

A credential moves through the following stages, depending on the action a user performs:

1. Enrollment: When no credentials exist yet, the first-time flow returns an enrollment URL instead of a token.
2. Creation: At creation, Kong Identity stores the credential in Token Vault. For static_secret providers, you generate the secret in the third-party service and store it in Token Vault yourself. For OAuth-based providers, the OAuth consent flow creates the credential and stores it automatically.
3. Refresh: For OAuth-based providers, Token Vault refreshes credentials automatically before they expire (see the provider’s refresh_buffer_seconds), with locking, to prevent concurrent requests from consuming a refresh token. If a refresh fails while the stored token is still valid, Token Vault keeps releasing the stored token.
4. Deletion/Revocation: You can revoke credentials independently of the provider itself. Admins can list and delete a user’s credentials with the /v2/directories/{directoryId}/principals/{principalId}/vault-credentials endpoints. Deleting a credential doesn’t delete the provider, but the user must re-enroll before an agent can call that provider on their behalf again.

Token Vault never exposes the credentials to the API that created them: it releases them to the AI Gateway for outbound calls without making the credentials accessible from any read endpoint.

Credential enrollment is a one-time process where a user grants Kong Identity permission to act on their behalf with a third-party service. During enrollment, Token Vault creates the credential for the first time.

When you configure a provider (for example, GitHub), Token Vault registers it as a service it knows how to talk to. It doesn’t mean any user has actually authorized anything yet, since there are still no credentials to hand back for Token Vault. The enrollment process follows these steps:

1. When a request comes in from the agent, Token Vault returns an enrollment URL, valid for 10 minutes, to open the third-party service’s OAuth consent screen. The screen lists exactly the scopes the provider requested (for example, repo on GitHub).
2. When the user approves, the third-party service redirects back to Token Vault’s callback endpoint and sends an authorization code.
3. Token Vault exchanges the authorization code for the third-party service’s access token and refresh token. This exchange happens only between Token Vault and the third-party service, not through the agent.
4. Token Vault writes a new credential row for the access token, encrypted with your directory’s vault key and stored for that user and provider. This is the credential that Token Vault releases to the AI Gateway on every future request.

Enrollment happens once per user and per provider, not per organization. If a second user wants to use GitHub with an agent, they need to go through enrollment, and get their own credentials stored in Token Vault. What is shared across the organization is the provider configuration (Client ID, scopes, endpoints).

For providers that support dynamic client registration (DCR), such as atlassian-rovo, you don’t need to create an app in the provider’s console: Token Vault registers the OAuth client with the provider at first use.

Shared credential enrollment

A shared credential means one credential for the whole directory, managed by an admin instead of per user. A shared authorization code provider is an OAuth provider with credential_type you set to shared. Authorization code providers default to user, so you must set credential_type: shared explicitly when you add the provider.

Then, enroll the shared credential:

1. An admin enrolls once on behalf of the directory: send a POST request to the /v2/directories/{directoryId}/vault/providers/{providerId}/credentials endpoint without a secret. The request fails if you send one.
2. Token Vault creates a pending credential and returns an enrollment_url.
3. The admin opens that URL and completes the provider’s OAuth consent.
4. The credential becomes active and Token Vault releases it to any authorized caller.

To re-enroll the shared account at any time, send a GET request to the /v2/directories/{directoryId}/vault/providers/{providerId}/credentials/{credentialId} endpoint. Each GET by credential ID returns a fresh enrollment_url, whether the credential is pending or active. The list endpoint never returns the enrollment_url.

To remove the shared credential, send a DELETE request to the same endpoint. The provider stays in place, but Token Vault has nothing to release until an admin enrolls again.

To set up Token Vault:

1. Enable it on the directory.
2. Add a trusted IdP.
3. Add your first provider (see Get started with the Kong Identity Token Vault).
4. Register a vault key to start using the provider.

To disable a provider without deleting it, for example as a kill switch, send a PATCH request to /v2/directories/{directoryId}/vault/providers/{providerId} with enabled: false.

A PUT on the same endpoint also sets enabled to false if you omit it.

A provider built on the static_secret template doesn’t run an OAuth flow. The setup steps are the following:

1. You generate the credential yourself in the third-party service, for example an API key or a personal access token.
2. You store the credential on the provider.

The static credential belongs to the directory instead of to an individual principal. A static_secret provider only accepts credential_type set to shared.

Store a static secret

To store a static secret:

1. Make sure the directory has a vault key. Kong Identity rejects a request to store a static secret with a 400 until you register one.
2. Create the provider: For static_secret, send only:
   • template_name
   • name
   • Optionally credential_type and base_url.

Kong Identity rejects client_id and client_secret with a 400 for this template:

PROVIDER_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/vault/providers" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "template_name": "static_secret",
       "name": "internal-api",
       "credential_type": "shared"
     }' | jq -r ".id"
)

The request accepts the following body parameters:

1. Store the credential on that provider by sending a POST request to the /v2/directories/{directoryId}/vault/providers/{providerId}/credentials endpoint. Kong Identity encrypts the value at rest and never returns it from any read endpoint:

CREDENTIAL_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/vault/providers/$PROVIDER_ID/credentials" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "secret": "'$STATIC_SECRET'"
     }' | jq -r ".id"
)

A shared provider can hold one default credential and any number of credentials with a selector. A second credential without a selector returns a 409. To rotate the secret, update the existing credential instead of creating another one.

Select a shared credential per principal

To release different shared credentials to different callers, for example one API key per team, add a selector and a priority to the credential:

curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/vault/providers/$PROVIDER_ID/credentials" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "secret": "'$TEAM_SECRET'",
       "selector": "\"'$GROUP_ID'\" in principal.groups",
       "priority": 10
     }'

• selector is a CEL expression (up to 1,024 characters) evaluated against the calling principal. It can use principal.id, principal.display_name, principal.groups (group IDs, including nested groups), and principal.metadata.
• priority is required with a selector, and not allowed without one. Each priority must be unique on the provider, otherwise the request returns a 409.

When the Kong AI Gateway requests a credential, Token Vault evaluates the selectors in ascending priority order and releases the first match. If no selector matches, it releases the default credential. If a selector fails to evaluate, the request fails instead of falling back to the next credential.

The following limitations apply to Token Vault:

• Policy enforcement: Token Vault isn’t a policy enforcement point, only Kong AI Gateway can enforce policies. Token Vault doesn’t handle authorization logic.
• Customer-managed encryption key: You register a public key on the directory (POST /v2/directories/{directoryId}/vault/keys) to encrypt Token Vault data. The key must be a PEM-encoded RSA (≥2048-bit) or EC (≥256-bit) key. The matching private key stays on the Kong AI Gateway, so Kong can’t decrypt stored credentials. A directory can hold up to 5 vault keys for rotation.
• Konnect only: Token Vault isn’t available for self-hosted/on-prem deployments.
• Unique issuer per trusted IdP: Within a directory, each trusted IdP must have a distinct issuer_url.
• No vault purge: You can’t disable Token Vault and delete all of its data in one step. Delete providers and credentials individually, or delete the directory.