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 a user's credential, session, or all sessions

POST
/scopes/{scopeId}/iam/users/{userId}/actions/revoke

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.

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.

userId*string

Identifier of the IAM user.

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

Request Body

application/json
  1. 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*string

What to revoke.

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

Response Body

Revocation applied; summary of the revoked material.

application/json
  1. response

Outcome of a revoke command.

userId*string

User whose material was revoked.

target*string

What was revoked.

Value in"session""all_sessions""mfa_device""api_key"
revokedCount*integer

Number of items revoked (e.g. sessions terminated by all_sessions).

revokedAt*string

When the revocation was applied (ISO).

Formatdate-time
curl -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"}