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
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.
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.
serviceAccountId*stringService account identifier.
Idempotency-Key?stringOptional; 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.
uuidapplication/json- body
Grant a role binding (role + scope) to a service account.
roleId*stringRole id to grant — a built-in id (owner, contributor, reader, billing-ops) or a custom role id (rol_…).
scopeType*ServiceAccountRoleScopeTypeScope 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.
"tenant""subscription""project"scopeName*stringName of the subscription or project the role applies to, resolved within the active scope.
Binding granted; returns the created role binding.
application/json- response
Role grant for the service account at subscription or project scope.
id*stringroleId*stringCatalog role id, e.g. roles/viewer, roles/compute.admin.
roleName*stringscopeType*ServiceAccountRoleScopeTypeScope 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.
"tenant""subscription""project"scopeName*stringName of the subscription or project the role applies to.
grantedBy*stringEmail of the principal that granted the binding.
grantedAt*stringdate-timecurl -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"}