Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Revoke an API token immediately
Immediately revokes an API token ("Revoke" / "Revoke token" in the UI). The token's status transitions to
REVOKED, the credential stops authenticating at once — any client still using it starts receiving 401
immediately — and the record remains visible in the token list and audit trail for traceability. Revocation
is permanent and cannot be undone; a replacement token must be created if access is needed again.
Validation: the token must exist and be visible in the active scope (NOT_FOUND otherwise); the
current status must permit revocation — an already REVOKED token is rejected with CONFLICT (409),
while revoking an EXPIRED token is also a state conflict; the caller must hold a token-management role
(owner|admin|contributor) or the request fails with FORBIDDEN.
Async & state: Synchronous command returning 200 with the updated token (ACTIVE/EXPIRED →
REVOKED, terminal). A resource.updated SSE frame with kind: iam.api_token carries a patch containing
the new status so open list and detail views refresh.
Errors: 401 unauthenticated; 403 caller lacks token-management permission; 404 unknown or out-of-scope
token; 409 token already revoked or otherwise in a state that does not permit revoke; 500 on backend
failure.
Idempotency/Concurrency: Supply Idempotency-Key; a replay with the same key returns the original
200 result without reprocessing. This operation does not check If-Match; a sent one is ignored.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
apiTokenId*stringIdentifier of the API token to revoke.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidToken revoked; the updated resource is returned.
application/json- response
A scoped programmatic API token. The full secret is never present on this schema.
id*stringToken identifier, e.g. "tok_a1b2".
name*stringToken name (lowercase letters, digits, hyphens), e.g. "ci-deploy-prod".
description*stringFree-text purpose description.
prefix*stringNon-sensitive secret prefix shown in the UI, e.g. "pc_live_7Qx9".
scopes*array<string>Granted permission scopes, e.g. "compute:write", "billing:read".
createdBy*stringDisplay name of the user who created the token.
createdAt*stringdate-timeexpiresAt*|Expiry timestamp, or null when the token never expires.
date-timelastUsedAt*|When the token last authenticated a call, or null if never used.
date-timelastUsedIp*|Source IP of the most recent call, or null if never used.
ipAllowlist*array<string>CIDR allowlist; empty array = no restriction (any IP).
status*ApiTokenStatusLifecycle status of an API token.
"ACTIVE""EXPIRED""REVOKED"curl -X POST "https://example.com/scopes/string/iam/api-tokens/string/actions/revoke"{ "id": "string", "name": "string", "description": "string", "prefix": "string", "scopes": [ "string" ], "createdBy": "string", "createdAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "lastUsedAt": "2019-08-24T14:15:22Z", "lastUsedIp": "string", "ipAllowlist": [ "string" ], "status": "ACTIVE"}