Rotate an API key

info

Ory Talos Secure API Keys on Ory Network is in preview. The HTTP API is versioned v2alpha1, and request and response shapes can change. Pin the version of the Ory SDK that you use.

Rotate an API key in Ory Talos Secure API Keys to replace its secret, for example after you share it by mistake or on a regular schedule.

Before you begin

• To manage keys in the Ory Console, you need the Owner or Developer role in the project. Members with the Viewer role can't view keys or send requests from the Playground.
• If an API key page in the Ory Console shows Enable Ory Talos, select Enable API keys. The change takes a short time to apply. See Eventual consistency.

To call the API, you need your project slug and a project API key.

A project API key is required for all administrative operations. To create one, read Creating API Keys.

The quickstart shows where to find the project slug and how to set up the TypeScript and Go SDKs. The examples on this page read both values from environment variables:

export PROJECT_SLUG=<your-project-slug>
export ORY_API_KEY=<your-project-api-key>

Rotate a key

Rotation replaces the secret of an issued key. Ory Talos Secure API Keys issues a new key with a new key ID and a new secret, and revokes the old key right away with the reason Superseded. There is no grace period: requests that use the old secret fail as soon as the rotation completes.

Ory Console

1. Go to API Keys → Keys in the Ory Console, open the row menu of the key, and select Rotate. On the key detail page, Rotate key is in the Danger zone section.
2. In the Rotate API key? dialog, select Rotate key.
3. Copy the new secret from the Your new API key secret dialog. The Ory Console shows it only once.

curl

Send POST /v2alpha1/admin/issuedApiKeys/{key_id}:rotate. The body can set a new name, scopes, metadata, rate_limit_policy, ip_restriction, or visibility for the new key. Fields that you leave out keep the values of the old key. The response has HTTP status 201 and contains the new key in issued_api_key, its secret in secret, and the revoked key in old_issued_api_key.

curl -sS -X POST "https://$PROJECT_SLUG.projects.oryapis.com/v2alpha1/admin/issuedApiKeys/${KEY_ID}:rotate" \
  -H "Authorization: Bearer $ORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq

The new key keeps the name, actor, scopes, metadata, rate limit, IP restrictions, visibility, and expiry time of the old key. Rotation doesn't extend the lifetime of a key: to get a later expiry, issue a new key. Tokens derived from the old key stay valid until they expire. You can't rotate a revoked key, and you can't rotate imported keys.

Rotate without downtime

Because rotation revokes the old secret right away, clients that still send it fail until they get the new secret. To switch keys without downtime:

1. Issue a second key for the same actor, with the same scopes.
2. Deploy the new secret to every client.
3. Confirm that all clients send the new key, for example by logging the key_id that the verify response returns.
4. Revoke the old key with the reason Superseded, REVOCATION_REASON_SUPERSEDED in the API.