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.
Get role detail
Retrieves a single IAM role for the role detail page, including the role definition (id, name,
description, built-in/custom flag, assignable scopes, created/updated timestamps), the full
permission matrix, and the member count used by the overview, permissions and JSON-policy panels.
Assignment rows shown in the detail tabs are served by the role-assignment sub-resources. The
rendered policy JSON document is derived client-side from the permission matrix; no
sensitive material is returned.
Validation: scopeId must be accessible to the caller (otherwise 403 FORBIDDEN); roleId
must reference an existing role visible in the scope — unknown or deleted roles → 404 NOT_FOUND.
Async & state: Synchronous read; no state change.
Errors: 401 when unauthenticated; 403 when the caller lacks iam:read in the scope; 404 when the
role does not exist in this scope; 500 on backend read failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required. The response carries
no ETag; PATCH and DELETE do not check If-Match.
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*stringRole identifier (e.g. owner, contributor, or a custom role id).
The role definition and permission matrix.
application/json- response
IAM role definition — built-in (owner, contributor, reader, billing-ops) or custom — with its permission matrix over platform resource keys.
id*stringRole identifier. Built-in ids are owner, contributor, reader, billing-ops; custom roles receive generated ids.
name*stringDisplay name, e.g. "Owner".
description*stringHuman-readable summary of what the role allows.
custom*booleanTrue when the role was created or cloned by the tenant.
members*integerNumber of principals currently assigned this role.
assignableScopes*array<>Scope levels this role can be assigned at.
builtIn*booleanBuilt-in roles are managed and cannot be edited or deleted.
createdAt*stringdate-timeupdatedAt*stringdate-timepermissions*Permission matrix — resourceKey (compute, storage, network, loadbalancer, kubernetes, observability, billing, budgets, iam, tokens, branding, audit) → access level.
curl -X GET "https://example.com/scopes/string/iam/roles/string"{ "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" }}