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.

Grant a role binding to a service account

POST
/scopes/{scopeId}/iam/service-accounts/{serviceAccountId}/bindings

Grants the service account a role at a subscription- or project-level scope (UI "Add binding" on the detail Bindings tab). Reuses the human-user role-assignment machinery: the same catalog role-assignment store, the same role ids (built-in owner/contributor/reader/billing-ops or a custom rol_… id) and the same scope model. The granted access takes effect immediately (an iam.assignment.changed event converges the enforcement caches). Validation: the account must exist and be visible in the scope (else 404 NOT_FOUND); roleId must name a grantable role (else 404 NOT_FOUND); scopeName must resolve to a subscription or project reachable in the scope (else 404 NOT_FOUND); caller must hold a role-management role (owner|admin) else 403 FORBIDDEN. Async & state: synchronous grant — 201 with the created binding. A terminal SUCCEEDED audit Operation is recorded and the account's bindingCount counter updates immediately. Errors: 401 unauthenticated; 403 lacks role-management permission; 404 unknown account, role or scope; 500 grant failure. Idempotency/Concurrency: Idempotency-Key is optional; when sent it is reserved atomically (single-winner) — replaying the same key returns the byte-identical binding and never grants twice; re-granting the same role+scope is an idempotent no-op that returns the existing binding.

Step-up: granting an owner-ranked role (built-in owner, or a custom role that ranks as owner) from a console session whose account has two-factor authentication needs the factor verified in the last 5 minutes, otherwise 403 MFA_STEP_UP_REQUIRED (verify with POST /auth/step-up, then retry). Other roles, and an owner row the member already holds, are not affected.

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.

serviceAccountId*string

Service account identifier.

Header Parameters

Idempotency-Key?string

Optional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.

Formatuuid

Request Body

application/json
  1. body

Grant a role binding (role + scope) to a service account.

roleId*string

Role id to grant — a built-in id (owner, contributor, reader, billing-ops) or a custom role id (rol_…).

scopeType*ServiceAccountRoleScopeType

Scope type a service-account role binding applies to. A tenant binding (scope name = the tenant's name) covers every subscription and project of the tenant.

Value in"tenant""subscription""project"
scopeName*string

Name of the subscription or project the role applies to, resolved within the active scope.

Response Body

Binding granted; returns the created role binding.

application/json
  1. response

Role grant for the service account at subscription or project scope.

id*string
roleId*string

Catalog role id, e.g. roles/viewer, roles/compute.admin.

roleName*string
scopeType*ServiceAccountRoleScopeType

Scope type a service-account role binding applies to. A tenant binding (scope name = the tenant's name) covers every subscription and project of the tenant.

Value in"tenant""subscription""project"
scopeName*string

Name of the subscription or project the role applies to.

grantedBy*string

Email of the principal that granted the binding.

grantedAt*string
Formatdate-time
curl -X POST "https://example.com/scopes/string/iam/service-accounts/string/bindings" \  -H "Content-Type: application/json" \  -d '{    "roleId": "string",    "scopeType": "tenant",    "scopeName": "string"  }'
{  "id": "string",  "roleId": "string",  "roleName": "string",  "scopeType": "tenant",  "scopeName": "string",  "grantedBy": "string",  "grantedAt": "2019-08-24T14:15:22Z"}