IAM policy concepts
An IAM policy is a container with three parts:
| Component | Description |
|---|---|
| Permission rules | Which API resource types and actions are allowed (for example, cloud_vpc + read, list) |
| Bindings | Which principals (users, service accounts, OIDC clients) receive the policy |
| Access conditions (optional) | IP and time-of-day restrictions on when the policy applies |
Use IAM policies when you need per-project, per-team, or per-environment access — for example, giving the DBA team read access to DBaaS clusters only in the production project, while developers get broader access in staging.
IAM policies work alongside organisation roles, not instead of them.
How effective permissions work
When a principal calls an API with a project context set:
- The platform checks organisation role rules (org-wide).
- It also checks IAM policy bindings on the active project.
- If either source grants the required permission on the resource (and resource identity, if scoped), access is allowed.
Important behaviours:
- IAM policies add access within a project; they do not remove organisation role permissions.
- Permission rules can target all instances of a resource type (empty
resourceIdentities) or specific resources (for example, one KMS key identity or one secret path). - For Secrets Manager, the resource identity is the secret path (for example,
/app/prod/db/password). For most other resources, the identity is the resource’s platform identity or slug. - Escalation prevention: When adding a permission rule, the caller must already hold the permissions being granted. You cannot delegate access you do not have.
Policy object reference
| Field | Customer meaning |
|---|---|
identity / slug | API identifiers |
system | Built-in platform policy |
isReadOnly | Cannot modify (system or inherited replica) |
replicateToChildren | Source policy propagates to descendants |
conditionals | Optional IP/time access conditions |
rules | Permission rules |
bindings | Principal attachments |
sourceIamPolicy | Present on replicas when loaded (points to parent source) |
system | isReadOnly | replicateToChildren | Type |
|---|---|---|---|
true | true | false | Built-in default |
false | false | true | Editable source (replicates downstream) |
false | true | false | Inherited replica |
Required headers
| Header | IAM policy APIs | Resource APIs |
|---|---|---|
Authorization | Required | Required |
X-Organisation-Identity | Required | Required |
X-Project-Identity | Required | Optional (scopes to project resources) |
Project resolution order on resource APIs: OIDC claim project → X-Project-Identity → ?project= query parameter.
Related documentation
- Permission rules — Rules, bindings, conditions, and replication
- Default policies — Built-in policy catalogue
- Projects — Project hierarchy and prerequisites