# Access model

How principals, roles, role assignments and permissions work together, how org-wide and project scopes differ, and how a request is authorized.

Access in Origin Cloud is granted by role assignments. A role assignment gives one principal one built-in role, either across the whole organization or for a single project. Every request is allowed only if one of the caller’s assignments covers the resource and carries the permission the request needs.

## Principals [#principals]

A principal is whoever or whatever is granted access. You refer to a principal by a typed identifier, in the same form whether you assign a role, revoke one, or check a permission.

| Principal | Format | Where to find the ID |
| --- | --- | --- |
| User | `user:<user-id>` | `userId` in `origin iam current-user`, or the `principal` column of `list-members` |
| Service account | `service_account:<service-account-id>` | The `principal` field returned when you create a service account or list them |

Both IDs are UUIDs. A user ID belongs to the person’s account and is the same in every organization they’re a member of.

## Roles [#roles]

A role is a named, fixed set of permissions. Every role is built in: you can assign and revoke them, but you can’t create, change or delete a role. Each role has a short ID such as `roles/owner` and a URN, which is what you pass to role commands, for example `urn:origin:cloud:iam::::tc/role/roles/owner`. The `list-roles` command shows every role with its URN and permissions. For the full catalog, see [Built-in roles](/docs/iam/roles).

## Permissions [#permissions]

A permission allows one action on one kind of resource. Its key has three dotted parts: the service, the resource type and the action, for example `network.vpc.list` or `iam.member.create`. Each API operation requires exactly one permission. When a request is refused, the error names the permission it needed:

```text
Insufficient permissions. This operation requires permission `iam.member.create` on `org/<org-id>`
```

The `permissions` command lists every permission the platform defines.

## Role assignments and scopes [#role-assignments-and-scopes]

A role assignment links a principal, a role and a scope. The scope is either the whole organization or one project in it.

| Scope | Where the role applies |
| --- | --- |
| Org-wide | The role applies to the organization itself and to every resource in every project of the organization, including projects created later. |
| Project scope | The role applies only to resources inside that one project. It doesn’t apply to the organization itself. |

All IAM operations, such as inviting members, assigning roles and creating service accounts, act on the organization. A project-scoped assignment therefore never allows them, even for `roles/owner`. To let someone manage access, assign the role org-wide. The billing roles must always be assigned org-wide; see [Billing access](/docs/platform/billing/billing-access).

Whoever creates an organization receives `roles/owner` and `roles/billing/administrator` org-wide. Anyone else holds only the roles you assign to them.

## Who can assign a role [#who-can-assign-a-role]

Assigning and revoking roles needs `iam.role.assign` or `iam.role.revoke` on the organization. On top of that, you can only assign or revoke a role whose permissions you hold yourself at the scope of the grant. For an org-wide grant, your org-wide assignments count. For a project-scoped grant, your org-wide assignments and your assignments in that project count. Nobody can use role management to gain access they don’t already have.

This applies to every path that changes a grant:

- [Assigning and revoking a role](/docs/iam/assign-roles).
- [Inviting a member](/docs/iam/manage-members#invite-a-member): you can only invite with a role you could assign. A pending invite is checked again when it’s applied. If the person who sent it can no longer assign the role by then, the invite is dropped.
- [Removing a member](/docs/iam/manage-members#remove-a-member): you must be able to revoke every role the member holds.

A request that would go beyond your own permissions is refused with `FORBIDDEN`. The error names the role and some of the permissions you lack. For example, Owner holds no billing permission, so an Owner can assign a billing role only if it also holds `roles/billing/administrator`. An IAM Editor can’t assign Owner.

## How a request is authorized [#how-a-request-is-authorized]

The following steps show how the platform decides whether to allow a request.

1. The request needs a permission on a resource.
1. The platform finds the principal’s role assignments in the resource’s organization.
1. For each assignment: if it’s org-wide or in the resource’s project, and its role contains the permission, the request is allowed. Otherwise the platform skips the assignment and checks the next one.
1. When no assignments are left, the request is refused with `FORBIDDEN`.

Permissions only add up. There are no deny rules, so holding a role never takes access away. The check runs on every request, so assigning or revoking a role takes effect on the principal’s next request. A refused request fails with the `FORBIDDEN` error.

## Repeated assignments and revocations [#repeated-assignments-and-revocations]

Assigning and revoking are idempotent. Assigning a role that the principal already holds at the same scope, with the same role URN, succeeds and changes nothing. Revoking a role that the principal doesn’t hold at that scope also succeeds and changes nothing.

A revocation matches the role URN and the scope exactly. An org-wide grant needs an org-wide revoke, and a project-scoped grant needs the same project. Use the role URN as it appears in the principal’s grants, because a grant created together with the organization carries the organization ID inside its URN. Don’t assemble that URN yourself: list the principal’s grants with `origin iam principal-grants --org-id <org-id> --principal <principal>` and copy the role URN of the grant you want to revoke. For the steps, see [Assign and revoke roles](/docs/iam/assign-roles).

## The last owner is protected [#the-last-owner-is-protected]

An organization always keeps at least one principal with an org-wide `roles/owner` assignment. The platform refuses with `CONFLICT` any revocation or member removal that would take the last org-wide owner away, including your own. A project-scoped owner doesn’t count. To hand over ownership, assign `roles/owner` org-wide to the new owner first, then revoke the old grant.

## Related [#related]

- [Built-in roles](/docs/iam/roles)
- [Assign and revoke roles](/docs/iam/assign-roles)
- [Check access](/docs/iam/check-access)
- [Organizations and projects](/docs/platform/organizations)