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.

List the principals holding a role in the active scope

GET
/scopes/{scopeId}/iam/roles/{roleId}/assignments

Returns the roster backing the role detail page "Assignments" tab: every principal (user or service account) granted this role at a scope covering the active scope — an assignment targeting this project directly (scopeKind=project) or the subscription above it (scopeKind=subscription). Each row carries the principal id, display name, principal type (user|service-account), the scope kind + human label the grant targets, and the grant timestamp (grantedAt). Principals whose user/service-account record is not visible in the active tenant are omitted, so the roster stays tenant-scoped. Validation: scopeId must reference a scope the caller can access (unknown → 404 NOT_FOUND); page/pageSize must be positive integers (else 422 VALIDATION_FAILED); the caller needs at least reader on IAM in the scope (else 403 FORBIDDEN). Async & state: Synchronous read; no state change; no SSE frames emitted. Errors: 401 missing/expired session; 403 caller lacks IAM read permission; 404 scope not found or not visible; 422 malformed query parameters; 500 read-model unavailable. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

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.

roleId*string

Identifier of the role whose assignments are listed.

Query Parameters

page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50

Response Body

Paginated roster of principals holding the role in the active scope.

application/json
  1. 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/roles/string/assignments"
{  "data": [    {      "id": "string",      "principalId": "string",      "name": "string",      "type": "user",      "scopeKind": "tenant",      "scopeLabel": "string",      "grantedAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}