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.
List and query IAM users in the active scope
Returns the IAM user records (members, guests, service accounts) visible in the active
tenant/subscription/project scope, as rendered by the Users page on route load. This single
operation also serves the UI's search/filter/sort/pagination controls (collapsed
iam.user.search_filter_sort): free-text q matches case-insensitively against the user's
name and email, the status chips narrow to ACTIVE / INVITED / INACTIVE (the Total chip clears
the filter), and sort accepts name or lastLogin with order/page/pageSize controlling
ordering and paging. Each row carries identity fields, role assignments, MFA state and last
login; emails are masked at the presentation layer, the API returns the canonical address.
No resource state is mutated.
Validation: scopeId must reference a tenant/subscription/project scope the caller can
access (404 via ErrNotFound when unknown); status must be one of ACTIVE|INACTIVE|INVITED;
sort must be name or lastLogin; page >= 1 and pageSize within bounds — otherwise
422 VALIDATION_FAILED.
Async & state: Synchronous read; no state change. Status changes performed elsewhere
(disable/enable/delete) surface to open consoles via resource.updated SSE frames
(kind iam.user, patch on status).
Errors: 401 when unauthenticated; 403 when the caller lacks an IAM-read-capable role
(owner|admin|contributor|reader) on the scope; 404 when scopeId is unknown; 422 on malformed
query parameters; 500 on read-model failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required.
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.
region?stringRestrict the result set to a single region.
^[a-z][a-z0-9-]{1,39}$q?stringFree-text search.
sort?stringField to sort by (entity-specific; defaults to the entity's natural order).
order?stringSort direction.
"asc""asc""desc"page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200).
1 <= value <= 20050status?stringFilter users by lifecycle status (UI counter chips Total/Active/Invited/Inactive).
"ACTIVE""INACTIVE""INVITED"type?stringFilter users by account type.
"MEMBER""GUEST""SERVICE_ACCOUNT"Paginated collection of IAM users visible in the active scope.
application/json- response
data*array<>meta*Pagination envelope metadata. List responses are always { data, meta } — never a naked array.
curl -X GET "https://example.com/scopes/string/iam/users"{ "data": [ { "id": "string", "name": "string", "email": "string", "title": "string", "avatarColor": "string", "status": "ACTIVE", "operatorLocked": true, "type": "MEMBER", "mfaEnabled": true, "lastLogin": "2019-08-24T14:15:22Z", "invitedAt": "2019-08-24T14:15:22Z", "createdAt": "2019-08-24T14:15:22Z", "lastPasswordChange": "2019-08-24T14:15:22Z", "department": "string", "manager": "string", "phone": "string", "employeeId": "string", "groups": [ "string" ], "mfaDevices": [ { "id": "string", "kind": "TOTP", "name": "string", "addedAt": "2019-08-24T14:15:22Z", "lastUsedAt": "2019-08-24T14:15:22Z", "primary": true } ], "apiKeys": [ { "id": "string", "name": "string", "prefix": "string", "createdAt": "2019-08-24T14:15:22Z", "lastUsedAt": "2019-08-24T14:15:22Z", "status": "ACTIVE" } ], "roles": [ { "role": "owner", "roleId": "string", "roleName": "string", "scopeKind": "tenant", "scopeLabel": "string", "assignedAt": "2019-08-24T14:15:22Z" } ], "activity": [ { "id": "string", "at": "2019-08-24T14:15:22Z", "action": "string", "resource": "string", "status": "SUCCESS" } ], "tags": [ { "key": "string", "value": "string" } ], "accessSummary": { "kind": "tenant", "subscriptions": 0, "projects": 0 } } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}