Organisation roles and IAM policies
Thalassa Cloud provides two binding scopes for access control. Both use the same built-in policy catalogue — see Default policies.
Organisation roles vs IAM policies
| Organisation role (supported) | IAM policy (recommended) | |
|---|---|---|
| Status | Existing; continues to work | Primary direction for new access control |
| Scope | Entire organisation | Single project (and descendants for replicated policies) |
| API path | /v1/iam/roles | /v1/projects/iam/policies |
| Project header | Not required | Required (X-Project-Identity) |
| Policy catalogue | Same policies as in the default catalogue | Identical permission rules |
| Naming | Policy name + slug | Policy name + slug (same values) |
| Customisation | Create additional custom roles | Create additional custom policies |
| Conditionals | Not supported | IP and time-of-day conditions (stored; runtime enforcement planned) |
| Inheritance | No | Yes — policies can replicate to child projects |
During the transition, a principal may hold both organisation role bindings and IAM policy bindings. Effective permissions for a request are the union of everything that applies to the active principal and project context.
When to use which:
- Organisation roles — org owners, finance, global administrators. See also RBAC roles for console-oriented role management.
- IAM policies — project admins, environment-specific teams, delegated access with optional conditions and inheritance.
Migrating to IAM policies
A practical path for teams moving to the new model:
- Enable projects on your organisation (
projectsfeature gate). - Create a project per team, environment, or workload boundary.
- Bind principals to IAM policies inside each project instead of (or in addition to) organisation roles.
- Use
replicateToChildrenon parent-project policies when child projects should inherit the same access. - Retain organisation roles where you still need org-wide access that is not tied to a project — for example billing (
org:financial) or org administration (org:admin).
There is no required cut-over date. Organisation role bindings are not revoked automatically when you adopt projects.
Assigning policies
IAM policies (recommended) — bind users, service accounts, or OIDC clients to policies within a project via the console or /v1/projects/iam/policies. When creating a project, the creator is automatically assigned the admin:all policy (admin slug).
Organisation roles (legacy, still supported) — bind principals via /v1/iam/roles or the organisation IAM settings in the console. A principal may hold multiple roles and policies; permissions are combined.
Related documentation
- Default policies — Built-in policy catalogue
- Projects — Creating and managing projects
- Permission rules — Rules, bindings, and replication
- RBAC roles — Organisation-wide role management in the console