Assign and revoke roles

Assign a role to give a user or service account access, and revoke it to take that access away. A change takes effect on the principal’s next request. To give a person access by email instead of by user ID, invite them.

Before you begin

An org-wide roles/owner or roles/iam/editor assignment, and every permission of the role you assign or revoke at the scope of the grant. For example, an Owner needs roles/billing/administrator as well to assign a billing role. See Who can assign a role.
Your organization ID (<org-id>) and, for a project-scoped grant, the project ID (<project-id>).
The principal, in the form user:<user-id> or service_account:<service-account-id>. list-members shows the principal of everyone who already has access. See Principals.

Assign a role

Find the URN of the role you want to assign.
Terminal window
```
origin iam list-roles --org-id <org-id>
```
For the permissions of each role, see Built-in roles.
Assign the role. Omit --project-id for an org-wide grant.
Terminal window
```
origin iam assign-role --org-id <org-id> \
  --principal user:<user-id> \
  --role-urn urn:origin:cloud:iam::::builtin/role/roles/viewer
```
To limit the grant to one project, add --project-id <project-id>. A project-scoped grant applies only to resources in that project; it never allows IAM operations. See Role assignments and scopes.
Verify the grant. The output lists every principal with its role URNs.
Terminal window
```
origin iam list-members --org-id <org-id>
```

Assigning a role the principal already holds at the same scope succeeds and changes nothing. A role URN that isn’t in the built-in catalog is refused with BAD_REQUEST. A role with permissions you don’t hold yourself at that scope is refused with FORBIDDEN, and so is revoking one.

Revoke a role

Find the role URN of the grant in the roleUrns of the principal in list-members. It’s the same URN that list-roles shows for the role, for example urn:origin:cloud:iam::::builtin/role/roles/owner.
Terminal window
```
origin iam list-members --org-id <org-id>
```
Revoke the role at the same scope it was assigned with. Omit --project-id for an org-wide grant, or pass the same project for a project-scoped one.
Terminal window
```
origin iam revoke-role --org-id <org-id> \
  --principal user:<user-id> \
  --role-urn urn:origin:cloud:iam::::builtin/role/roles/viewer
```
Optionally, run list-members again to check that the role URN is gone from the principal.

If the principal holds no grant of that role at that scope, the platform refuses with NOT_FOUND and changes nothing. Check the scope: an org-wide grant isn’t revoked by a request that names a project, and the reverse.

If revoking would leave the organization without an org-wide owner, the platform refuses with CONFLICT. Assign roles/owner org-wide to someone else first. See The last owner is protected.

To take away every role a principal holds in the organization at once, remove the member instead.

Using the API

The assignRole and revokeRole mutations take the same input. Omit projectId for an org-wide grant.

mutation {
  iam {
    assignRole(input: {
      orgId: "<org-id>"
      principal: "user:<user-id>"
      roleUrn: "urn:origin:cloud:iam::::builtin/role/roles/viewer"
    })
  }
}

Access model
Built-in roles
assign-role and revoke-role commands
Audit log – every assignment and revocation is recorded

Before you begin

Assign a role

Revoke a role

Using the API

Related