Manage API keys

Generate, rotate, and revoke API keys for workload connections.

About this task

As a security admin, you manage the full lifecycle of API keys for workload connections. You can generate new keys, rotate existing keys with a grace period, and revoke keys that are no longer needed.

Before you begin

You must have a security admin role to manage API keys.
An API key workload connection must already exist. See Create an API Key workload connection.

On the Okta Privileged Access dashboard, go to DevOps Administration > Workload connections.
Click the name of your API key workload connection.
Click Manage keys.
Click Create API Key.
Complete the following details:
1. Enter a unique, descriptive name for this API key (for example, backend-prod-api-key).
2. Optionally assign key-value pairs that apply specifically to this key. These attributes are included in authentication tokens and used for workload role mapping (for example, {"env": "prod", "service": "backend"}).
Click Save.
On the confirmation page, copy the API key immediately.

Warning:
This is the only time the API key is visible. If you navigate away without copying, you can't retrieve it. Request a new key to replace the lost one.
Deliver the key to the workload team through a secure channel.

Issue	Resolution
Lost API key	If the workload team lost the API key without copying it, start a rotation on the existing API key to get a new key. This allows the workload team to hold onto the API key without re-submitting the form with claims. After the workload team deploys the new key, complete the rotation to sunset the old and lost key.
Workload still using old key after rotation	If a workload is still using the old key after you finalized the rotation, authentication fails. Verify that the workload team deployed the new key correctly and that the environment variable or configuration is set to the new key value.
Delayed revocation	If a revoked key still authenticates after revocation, the token issuer's cache hasn't yet expired. This is expected behavior and typically resolves within five minutes. Revocation is a synchronous action—if it fails, an error appears immediately after clicking Revoke.

From the API Keys tab of a workload connection, you can also rotate or revoke a key.

Rotate: Generates a new secret for an Active key while keeping the old secret valid during a transition period. The new key is visible only once, so copy it immediately and deliver it to the workload team. After the workload team deploys the new key, click Complete rotation to invalidate the old secret, or click Cancel Rotation to discard the new secret and keep the original.

Revoke: Immediately invalidates a key. Use this when a key is compromised or no longer needed. The token issuer caches API key metadata, so a revoked key may still authenticate for up to five minutes until the cache expires.