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 a user's credential, session, or all sessions
Revokes credential material belonging to the selected user. The detail view exposes four
revoke surfaces that converge on this command: revoke a single login session, "Revoke all
sessions" (signs the user out of every device except the current session), revoke an enrolled
MFA device (the user must re-enroll to use it again), and revoke a personal API key (any
integration using it stops working immediately; the key is marked EXPIRED rather than deleted
so the audit trail is preserved). The request body's target discriminates which kind is
revoked and targetId identifies the specific session, device, or key.
Validation: userId must exist and be visible in scopeId (404 via ErrNotFound); target
must be one of session|all_sessions|mfa_device|api_key — 422 VALIDATION_FAILED otherwise;
targetId is required for session, mfa_device and api_key and must reference an item belonging
to this user (404 via ErrNotFound when unknown); revoking an already-revoked key or an expired
session returns 409 CONFLICT; the caller must hold owner|admin on the scope.
Async & state: Synchronous — returns 200 with a revocation result summarising what was
revoked and how many items were affected. The affected sub-resources flip state immediately
(session removed, MFA device unenrolled, API key status ACTIVE → EXPIRED) and a
resource.updated SSE frame (kind iam.user, patch on sessions/mfaDevices/apiKeys) is
emitted for open detail views.
Errors: 401 unauthenticated; 403 when the caller lacks owner|admin on the scope; 404 when
scopeId/userId/targetId is unknown; 409 when the item is already revoked or its state
forbids revocation; 422 on a malformed body; 500 on command failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended) because the UI can
retry; replaying
the same key returns the original result without double-counting. Revocation is inherently
idempotent per target — repeating it cannot resurrect or re-revoke material.
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.
userId*stringIdentifier of the IAM user.
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.
uuidapplication/json- body
Discriminated revoke command covering the detail view's revoke surfaces — a single session, all other sessions, an MFA device, or a personal API key.
target*stringWhat to revoke.
"session""all_sessions""mfa_device""api_key"targetId?|Identifier of the session, MFA device, or API key to revoke. Required for session, mfa_device and api_key; null/omitted for all_sessions.
Revocation applied; summary of the revoked material.
application/json- response
Outcome of a revoke command.
userId*stringUser whose material was revoked.
target*stringWhat was revoked.
"session""all_sessions""mfa_device""api_key"revokedCount*integerNumber of items revoked (e.g. sessions terminated by all_sessions).
revokedAt*stringWhen the revocation was applied (ISO).
date-timecurl -X POST "https://example.com/scopes/string/iam/users/string/actions/revoke" \ -H "Content-Type: application/json" \ -d '{ "target": "session" }'{ "userId": "string", "target": "session", "revokedCount": 0, "revokedAt": "2019-08-24T14:15:22Z"}