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.

Remove an IAM user from the organization

DELETE
/scopes/{scopeId}/iam/users/{userId}

Permanently removes the selected user from the organization (the "Remove" action in the Users page row menus and the detail header). Removal revokes all role assignments, group memberships, active sessions, MFA enrollments and personal API keys, and cannot be undone from the console. The user disappears from the scoped list once the deletion workflow completes; failure leaves the record in a recoverable, queryable state. Validation: userId must exist and be visible in scopeId (404 via ErrNotFound); deletion is blocked with 409 DEPENDENCY_BLOCKED while unresolved dependants exist — e.g. the user is the sole owner of the subscription, owns active service-account bindings, or is referenced by a pending access review; destructive-action permission (owner|admin) is enforced. Async & state: Asynchronous — returns 202 with an Operation record. The user transitions through a deleting state to terminal removed; resource.updated SSE frames (kind iam.user, patch on status) are emitted during teardown and a final resource.deleted frame removes the row from open lists. Errors: 401 unauthenticated; 403 when the caller lacks destructive permission on the scope; 404 when scopeId/userId is unknown; 409 DEPENDENCY_BLOCKED when attachments, dependants, locks or retention rules block removal; 412 when the If-Match revision is stale; 500 on workflow failure. Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted and a sent one is ignored. The removal is applied inline and a new already-SUCCEEDED Operation is returned; repeating it after it succeeded answers 404 NOT_FOUND because the member's user row is gone, so no second teardown runs. An optional If-Match with the user's ETag (from the detail read) is honoured: a stale one is refused 412 before anything is removed; without it the removal proceeds.

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

If-Match?string

ETag for optimistic concurrency on mutations/deletes; mismatch results in 412.

Response Body

Deletion accepted; Operation record tracking the removal workflow.

application/json
  1. response

A long-running operation record. GET /operations/{operationId} returns its current state.

id*string

Operation identifier, unique platform-wide.

action*string

Canonical action id that started this operation, e.g. compute.instance.create.

state*OperationState

State machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.

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

Range0 <= value <= 100
error?|null

Populated only when state is FAILED (or CANCELLED with partial rollback notes).

warning?|null

Non-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*string
updatedAt*string
curl -X DELETE "https://example.com/scopes/string/iam/users/string"
{  "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"}