# Assign and revoke roles

Grant a built-in role to a user or service account org-wide or for one project, and revoke it again at exactly the scope it was granted.

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](/docs/iam/manage-members#invite-a-member).

## Before you begin [#before-you-begin]

<BeforeYouBegin>

- 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](/docs/iam/access-model#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](/docs/iam/access-model#principals).

</BeforeYouBegin>

## Assign a role [#assign-a-role]

1. Find the URN of the role you want to assign.

   ```sh
   origin iam list-roles --org-id <org-id>
   ```

   For the permissions of each role, see [Built-in roles](/docs/iam/roles).

1. Assign the role. Omit `--project-id` for an org-wide grant.

   ```sh
   origin iam assign-role --org-id <org-id> \
     --principal user:<user-id> \
     --role-urn urn:origin:cloud:iam::::tc/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](/docs/iam/access-model#role-assignments-and-scopes).

1. Verify the grant. The output lists every principal with its role URNs.

   ```sh
   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 [#revoke-a-role]

1. 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::::tc/role/roles/owner`, except for a grant created together with the organization, which carries the organization ID inside its URN. Copy the URN from `list-members` or from `origin iam principal-grants --org-id <org-id> --principal <principal>` rather than typing it.

   ```sh
   origin iam list-members --org-id <org-id>
   ```

1. 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.

   ```sh
   origin iam revoke-role --org-id <org-id> \
     --principal user:<user-id> \
     --role-urn urn:origin:cloud:iam::::tc/role/roles/viewer
   ```

1. 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](/docs/iam/access-model#the-last-owner-is-protected).

To take away every role a principal holds in the organization at once, [remove the member](/docs/iam/manage-members#remove-a-member) instead.

## Using the API [#using-the-api]

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

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

## Related [#related]

- [Access model](/docs/iam/access-model)
- [Built-in roles](/docs/iam/roles)
- [`assign-role`](/docs/iam/reference/cli#assign-role) and [`revoke-role`](/docs/iam/reference/cli#revoke-role) commands
- [Audit log](/docs/iam/audit-log) – every assignment and revocation is recorded