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.
Disable an IAM user
Suspends the selected ACTIVE user's MEMBERSHIP in this tenant (the danger "Disable" action in
the detail header and the "Deactivate" row/bulk action in the Users page). This tenant's scopes stop
resolving for the person at once. Their sign-in is closed (all sessions ended) only when no other
active tenant membership remains -- suspending a member here never locks them out of another
tenant. Role assignments, group memberships and credentials are retained so re-enabling restores
prior access. The resulting INACTIVE status is available to subsequent reads and list filters.
Validation: userId must exist and be visible in scopeId (404 via ErrNotFound); the
current state must permit disable — a user already INACTIVE, still INVITED, or being the last
remaining owner of the subscription is rejected with 409 CONFLICT; the caller must hold
owner|admin on the scope.
Async & state: Asynchronous — returns 202 with an Operation record. State transition
ACTIVE → disabling → terminal INACTIVE; session teardown happens during the transition.
resource.updated SSE frames (kind iam.user, patch on status) are emitted as the
transition starts and completes.
Errors: 401 unauthenticated; 403 when the caller lacks owner|admin on the scope; 404 when
scopeId/userId is unknown; 409 when the current state does not permit disable (already
inactive, invited, or last-owner protection); 412 when the If-Match revision is stale; 500 on
command failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended) because the UI can
retry; replaying
the same key returns the original Operation. If-Match against the user's ETag is honoured
(412 on mismatch) so a concurrent status change is not blindly overridden.
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.
uuidIf-Match?stringETag for optimistic concurrency on mutations/deletes; mismatch results in 412.
Disable accepted; Operation record tracking the transition to INACTIVE.
application/json- response
A long-running operation record. GET /operations/{operationId} returns its current state.
id*stringOperation identifier, unique platform-wide.
action*stringCanonical action id that started this operation, e.g. compute.instance.create.
state*OperationStateState machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.
"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"resourceKind?|Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.
resourceId?|Identifier of the target resource; null until the resource is allocated.
resourceName?|Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).
principalId?|Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.
sourceIp?|Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).
progressPercent?|Best-effort progress; null when the action does not report progress.
0 <= value <= 100error?|nullPopulated only when state is FAILED (or CANCELLED with partial rollback notes).
warning?|nullNon-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.
startedAt?|When the worker began executing; null while PENDING.
finishedAt?|When a terminal state was reached; null while transitional.
createdAt*stringupdatedAt*stringcurl -X POST "https://example.com/scopes/string/iam/users/string/actions/disable"{ "id": "string", "action": "string", "state": "PENDING", "resourceKind": "string", "resourceId": "string", "resourceName": "string", "principalId": "string", "sourceIp": "string", "progressPercent": 0, "error": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "warning": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "startedAt": "string", "finishedAt": "string", "createdAt": "string", "updatedAt": "string"}