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
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.
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.
roleId*stringIdentifier of the role whose assignments are listed.
page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200).
1 <= value <= 20050Paginated roster of principals holding the role 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/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 }}