API authorization

Every organisation API request is authenticated, then checked against IAM bindings. Understanding where you attach permissions and which bindings an endpoint evaluates helps you diagnose access issues and design least-privilege roles.

This page covers organisation scope APIs. For built-in policy catalogues, see Default policies.

Request context

Requirement	Details
Authentication	Valid bearer token (user session, personal access token, service-account credentials, or OIDC client token)
Organisation	`X-Organisation-Identity` header (organisation slug or UUID), or OIDC claim / query-parameter fallback
Project (optional)	`X-Project-Identity` selects the active project for project-scoped endpoints; omitting it defaults to the organisation root project

X-Project-Identity is required when managing IAM policies for a specific (non-root) project via /v1/projects/iam/policies. It has no effect on organisation-scoped endpoints — see IAM evaluation scope.

Project resolution order on resource APIs: OIDC claim project → X-Project-Identity → ?project= query parameter.

Permission sources

You attach bindings in one of two places:

Organisation role bindings (/v1/iam/roles) — organisation-wide
IAM policy bindings (/v1/projects/iam/policies) — per project

Which bindings are evaluated for a given API call depends on the endpoint’s IAM evaluation scope (below). The organisation owner is automatically bound to the admin:all policy (admin slug) with full access.

See Organisation roles and IAM policies for when to use each model.

IAM evaluation scope

Each endpoint uses one of two IAM evaluation scopes. This is separate from where you attach bindings — it controls which bindings the API considers.

Scope	Binding sources evaluated	`X-Project-Identity`
Organisation	Organisation role bindings only	Ignored for authorization (project IAM policies never apply)
Project	Organisation role bindings and IAM policy bindings for the active project	Selects the project; omitting it uses the organisation root project

Organisation-scoped endpoints only accept permissions from organisation role bindings. A principal with only a project IAM policy — for example k8s:admin bound in project prod — is denied on organisation-scoped endpoints such as listing memberships, even when X-Project-Identity: prod is set.

Project-scoped endpoints accept the union of organisation role bindings and IAM policy bindings for the active project. Most workload APIs (Kubernetes, IaaS, DBaaS, DNS, KMS, Secrets Manager, and others) use this scope.

Quick reference by API area

IAM evaluation scope	API areas
Organisation	Members, invites, teams, quotas, notification settings, organisation roles (`/v1/iam/roles`), projects CRUD (`/v1/projects`), audit, usage, billing (invoices, mandates, credits, budgets, pricing, savings plans, contracts), beta feature signups, organisation contacts
Project	IAM policies (`/v1/projects/iam/policies`), service accounts, federated identities and providers, SSH keys, Kubernetes, IaaS, DBaaS, DNS, KMS, Secrets Manager, container registry, observability workspaces, cloud-init templates, quick launch, etc
Personal	`/v1/me`, `/v1/regions`, personal access tokens, access credentials (membership check), notifications, dashboard, helpdesk, and some read-only catalogue endpoints

How permissions are evaluated

When an endpoint requires multiple resources, all checks must pass (logical AND).
Permission type * (wildcard) satisfies any standard action on the matched resource.
Resource identity in the URL is matched against resourceIdentities in IAM rules; an empty list means all instances.

Permission types

Type	Used for
`create`, `read`, `update`, `delete`, `list`	Standard resource lifecycle
`*`	All standard actions
`push`, `pull`	Container registry
`encrypt`, `decrypt`, `sign`, `verify`, `hmac`, `verify-hmac`, `rotate`, `export`	KMS keys
`getSecretValue`, `putSecretValue`	Secrets Manager payloads

Assignable resource types use snake_case identifiers in IAM rules (for example cloud_vpc, kubernetes_cluster, kms_key, secret). Use GET /v1/projects/iam/policies/resources or GET /v1/iam/roles/resources for the authoritative list in your organisation.

Special cases

Some endpoints do not use standard IAM middleware:

API area	Authorization model
`/v1/regions`	Authenticated user (no organisation header or IAM permission required)
`/v1/me`	Authenticated user (no organisation-scoped IAM permission)
`/v1/personal-access-tokens`	Authenticated user manages their own tokens
`/v1/access-credentials`	Organisation membership check; IAM resource `access_credentials` for delegated admin
`/v1/notifications`, `/v1/dashboard`	Organisation context required; no route-level IAM check
`/v1/helpdesk`	Authenticated human user who is an organisation member
Kubernetes version catalogue	Authenticated with organisation context; no IAM permission middleware

Practical examples

Denied despite project binding: A service account has iaas:FullAccess only as a project IAM policy in staging. Calls to GET /v1/memberships fail because membership APIs are organisation-scoped. Bind an organisation role (for example org:auditor) if org-wide list access is required.

Union of bindings: A user has organisation role user:read and project policy k8s:admin in prod. With X-Project-Identity: prod, they can administer Kubernetes in that project. Without a project header, project IAM policies do not apply and they keep only the organisation role permissions (on project-scoped APIs, evaluated against the root project).

Compound checks: Downloading a kubeconfig typically requires permissions on the cluster and on kubeconfig / API proxy resources. Granting only kubernetes_cluster read is not enough — use a built-in policy such as kubernetes:AllowKubeConfigDownload or an equivalent custom rule set.