Get started with the Kong Identity Token Vault

Send a PATCH request to the /v2/directories/{directoryId} endpoint with vault_enabled set to true:

curl -X PATCH "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "vault_enabled": true
     }'

PATCH is a partial update, so any field you omit keeps its current value. You only need to send vault_enabled.

Confirm the vault is enabled by sending a GET request to the same endpoint and capturing the vault_enabled field:

VAULT_ENABLED=$(curl -X GET "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" | jq -r ".vault_enabled"
)

Print the captured value. It returns true when the Token Vault is active on the directory:

echo $VAULT_ENABLED

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:

curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/trusted-idps" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "issuer_url": "'$ISSUER_URL'",
       "jwks_uri": "'$JWKS_URI'",
       "display_name": "Okta",
       "vault_access_enabled": true
     }'

The issuer_url must match the iss claim of your IdP’s tokens exactly. If you omit jwks_uri, Kong Identity discovers it from the issuer’s /.well-known/openid-configuration document.

For all the available parameters, see Trusted IdP.

Verify the configuration by sending a GET request to the same endpoint:

curl -X GET "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/trusted-idps" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

Send a POST request to the /v2/directories/{directoryId}/vault/providers endpoint to create a provider from the github 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" \
     --json '{
       "template_name": "github",
       "name": "github-prod",
       "client_id": "'$GITHUB_CLIENT_ID'",
       "client_secret": "'$GITHUB_CLIENT_SECRET'",
       "scopes": [
         "repo",
         "read:user"
       ]
     }' | jq -r ".id"
)

Confirm that the Token Vault contains the provider:

List the providers registered for the directory. The response includes github-prod:

curl -X GET "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/vault/providers" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

Check that the provider is enabled by sending a GET request to the provider endpoint, using the PROVIDER_ID captured when you added it. The response contains "enabled": true, "template_name": "github", and "credential_type": "user":

curl -X GET "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/vault/providers/$PROVIDER_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

Before users can enroll to an AI service like MCP servers, you need to upload an encryption key to the Token Vault.

The Token Vault encrypts every credential it stores with a public key that you register on the directory. Kong Identity keeps only the public key, and the matching private key stays on the Kong AI Gateway, so Kong Identity can’t decrypt your credentials. Kong Identity rejects a request to store a static secret until the directory has a vault key.

1. Generate an RSA key pair. The key must be at least 2048 bits (RSA) or 256 bits (EC):

   openssl genrsa -out vault-private.pem 2048
   openssl rsa -in vault-private.pem -pubout -out vault-public.pem

   Copied!

   Keep vault-private.pem safe. Don’t share it or commit it to source control.

2. Export the public key as a single line, with the newlines escaped so it fits in a JSON body:

   export VAULT_PUBLIC_KEY=$(awk 'NF {printf "%s\\n", $0}' vault-public.pem)

   Copied!

3. Send a POST request to the /v2/directories/{directoryId}/vault/keys endpoint:

curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/vault/keys" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "my-vault-key",
       "public_key": "'$VAULT_PUBLIC_KEY'"
     }'

A directory can hold up to 5 vault keys, which lets you rotate keys over time.

Users now enroll their GitHub credential the first time an agent calls GitHub through Kong AI Gateway. For details, see Credential enrollment. After uploading the encryption key, you can see your GitHub provider as an option for authenticating Kong AI Gateway services, like MCP servers. For the full configuration, see AI MCP Server upstream authentication with Token Vault. To disable the provider without deleting it, for example as a kill switch, send a PATCH request to /v2/directories/{directoryId}/vault/providers/{providerId} with enabled: false.