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 roles in the active scope

GET
/scopes/{scopeId}/iam/roles

Returns the built-in and custom IAM roles visible in the active tenant/subscription/project scope, including each role's permission matrix (resourceKey → manage|read|none), assignable scope levels, member count, and built-in/custom flag. Backs the Roles page route load (role cards plus the per-role permission matrix panel). This single endpoint also serves search/filter/sort/pagination: q matches role id, name and description; builtIn filters built-in vs custom roles; sort/order accept role columns (name, members, updatedAt); page/pageSize paginate. No mutation occurs. Validation: scopeId must reference a tenant/subscription/project scope the caller can access (UNKNOWN_SCOPE → 404 via routing, no access → 403 FORBIDDEN); page/pageSize must be positive integers and order one of asc|desc, otherwise 422 VALIDATION_FAILED. Async & state: Synchronous read; no state change. Errors: 401 when the session is missing or expired; 403 when the caller lacks iam:read in the scope; 422 for malformed pagination/sort parameters; 500 on backend read-model failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required. Supports ETag-based revalidation of the collection snapshot.

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.

Query Parameters

region?string

Restrict the result set to a single region.

Match^[a-z][a-z0-9-]{1,39}$
q?string

Free-text search.

sort?string

Field to sort by (entity-specific; defaults to the entity's natural order).

order?string

Sort direction.

Default"asc"
Value in"asc""desc"
page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50
builtIn?boolean

Filter to built-in roles (true) or custom roles (false).

assignableScope?string

Only return roles assignable at the given scope level.

Value in"subscription""project"

Response Body

Paginated collection of roles 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"
{  "data": [    {      "id": "string",      "name": "string",      "description": "string",      "custom": true,      "members": 0,      "assignableScopes": [        "tenant"      ],      "builtIn": true,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "permissions": {        "property1": "manage",        "property2": "manage"      }    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}