Key Revocation - Unkey Docs

When a key is compromised or a user's access should end, you can revoke it immediately. Unkey supports both permanent deletion and temporary disabling.

When to use this#

Security incident

Key was leaked in a public repo or logs. Delete it immediately.

User offboarding

Customer canceled or employee left. Revoke their API access.

Suspicious activity

Unusual traffic patterns. Disable the key while investigating.

Billing issues

Payment failed. Temporarily disable until resolved.

Delete vs Disable#

Action	Effect	Reversible?	Use when
Delete	Permanently removes the key	No	Key is compromised, user churned
Disable	Key exists but can't authenticate	Yes	Temporary suspension, investigation

Delete a key permanently#

Use when the key should never work again:

curl -X POST https://api.unkey.com/v2/keys.deleteKey \  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \  -H "Content-Type: application/json" \  -d '{    "keyId": "key_..."  }'

The key is invalidated within 60 seconds globally.

Warning

Deletion is permanent. The key cannot be recovered. If you might need to restore access, use disable instead.

Disable a key temporarily#

Use when you want to suspend access but may restore it later:

curl -X POST https://api.unkey.com/v2/keys.updateKey \  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \  -H "Content-Type: application/json" \  -d '{    "keyId": "key_...",    "enabled": false  }'

Verification response when disabled:

{  "data": {    "valid": false,    "code": "DISABLED",    "keyId": "key_..."  }}

Re-enable a disabled key#

try {  const { meta, data } = await unkey.keys.updateKey({    keyId: "key_...",    enabled: true,  });} catch (err) {  console.error(err);  return Response.json({ error: "Internal error" }, { status: 500 });}

The key works again immediately.

Propagation time#

Delete: Up to 60 seconds for global invalidation
Disable: Up to 60 seconds for global propagation

For immediate revocation of a compromised key, you may want to also:

Rotate any affected secrets downstream
Review audit logs for unauthorized access
Alert the user if appropriate

Bulk revocation#

To revoke all keys for a specific user, query their keys first:

try {  let cursor: string | undefined;  // Page through all keys for the user  do {    const { data, pagination } = await unkey.apis.listKeys({      apiId: "api_...",      externalId: "user_123",      cursor,    });    for (const key of data) {      await unkey.keys.deleteKey({ keyId: key.keyId });    }    cursor = pagination?.hasMore ? pagination.cursor : undefined;  } while (cursor);} catch (err) {  console.error(err);  return Response.json({ error: "Internal error" }, { status: 500 });}

Tip

For security incidents, consider using key rerolling if you need to maintain the user's configuration while replacing the compromised key.

Next steps#

Key rerolling

Replace a key while preserving its configuration

Audit logs

Track who revoked which keys