Identity & Access Management

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

POST
/scopes/{scopeId}/iam/api-tokens/{apiTokenId}/actions/revoke

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

apiTokenId*string

Identifier of the API token to revoke.

Header Parameters

Idempotency-Key?string

Optional; 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.

Formatuuid

Response Body

Token revoked; the updated resource is returned.

application/json
  1. response

A scoped programmatic API token. The full secret is never present on this schema.

id*string

Token identifier, e.g. "tok_a1b2".

name*string

Token name (lowercase letters, digits, hyphens), e.g. "ci-deploy-prod".

description*string

Free-text purpose description.

prefix*string

Non-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*string

Display name of the user who created the token.

createdAt*string
Formatdate-time
expiresAt*|

Expiry timestamp, or null when the token never expires.

Formatdate-time
lastUsedAt*|

When the token last authenticated a call, or null if never used.

Formatdate-time
lastUsedIp*|

Source IP of the most recent call, or null if never used.

ipAllowlist*array<string>

CIDR allowlist; empty array = no restriction (any IP).

status*ApiTokenStatus

Lifecycle status of an API token.

Value in"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"}