Self-revocation

Self-revocation lets an API key holder revoke their own key by proving possession of the secret. It is the only operation on the self-service surface and does not require admin access.

Prerequisites

You need a running Ory Talos server. See the quickstart to start one locally.

When to use self-revocation

• Key compromise — a user finds their key is leaked and revokes it immediately.
• User-initiated cleanup — a user decommissions an integration and revokes unused keys.
• Security automation — an automated system detects anomalous usage and revokes the key.

Self-revoke a key

First, issue a key to get a secret:

CLI

export SELF_REVOKE_SECRET=$(talos keys issue "self-revoke-demo" \
  --actor user_99 \
  --scopes "read:data" \
  --format json \
  -e "$TALOS_URL" 2>/dev/null | jq -er '.secret')

curl

ISSUE_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "self-revoke-demo",
    "actor_id": "user_99",
    "scopes": ["read:data"]
  }')

export SELF_REVOKE_SECRET=$(echo "$ISSUE_RESPONSE" | jq -er '.secret')

Send the full key secret as proof of possession:

CLI

talos keys self-revoke "$SELF_REVOKE_SECRET" \
  --reason key_compromise \
  -e "$TALOS_URL"

curl

curl -s -X POST "$TALOS_URL/v2alpha1/apiKeys:selfRevoke" \
  -H "Content-Type: application/json" \
  -d "{
    \"credential\": \"$SELF_REVOKE_SECRET\",
    \"reason\": \"REVOCATION_REASON_KEY_COMPROMISE\"
  }"
echo ""
echo "Key self-revoked"

Verify the key is no longer active:

CLI

talos keys verify "$SELF_REVOKE_SECRET" --no-cache -e "$TALOS_URL" || true
echo "Self-revocation confirmed"

curl

VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -d "{\"credential\":\"$SELF_REVOKE_SECRET\"}")

echo "$VERIFY_RESPONSE" | jq .

if echo "$VERIFY_RESPONSE" | jq -e '.is_valid == false' > /dev/null 2>&1; then
  echo "Self-revocation confirmed"
else
  echo "ERROR: Key should have been revoked"
  exit 1
fi

The request requires credential (the full API key secret) and optionally reason (revocation reason enum). For the complete field reference, see the SelfRevokeAPIKey API reference.

Self-revocation works only for issued and imported API keys. Derived tokens (JWTs and macaroons) are stateless and can't be revoked.

Self-revocation accepts the same standard reasons as admin revocation, except REVOCATION_REASON_PRIVILEGE_WITHDRAWN. Talos reserves that reason for admin-initiated revocations and rejects it here with InvalidArgument, because a key holder can't withdraw their own privileges. Common self-service reasons are REVOCATION_REASON_KEY_COMPROMISE for a leaked secret, REVOCATION_REASON_SUPERSEDED for self-service rotation, and REVOCATION_REASON_AFFILIATION_CHANGED when the user or integration goes away but the secret isn't compromised. For guidance on choosing a reason, see the revocation reasons section in the key lifecycle guide.

A successful self-revocation returns an empty response with HTTP status 200 OK. Talos revokes the key immediately.

Admin versus self-revocation

	Admin revocation	Self-revocation
Endpoint	POST /v2alpha1/admin/issuedApiKeys/{key_id}:revoke	POST /v2alpha1/apiKeys:selfRevoke
Surface	Admin	Self-service
Authentication	Requires admin access	Proof of possession (key secret)
Identifier	Key ID	Key secret
PRIVILEGE_WITHDRAWN	Allowed	Not allowed

Admin revocation has a separate endpoint per key type: use POST /v2alpha1/admin/issuedApiKeys/{key_id}:revoke for issued keys and POST /v2alpha1/admin/importedApiKeys/{key_id}:revoke for imported keys.

Next steps

• Key lifecycle — admin-side key management
• Error handling — handle revocation errors