# Manage organization members

Invite people to your organization by email, list members and pending invites, remove a member's access, and cancel an invite before it applies.

A member is any principal with at least one role assignment in your organization. You add people by email with an invite, which grants them one role org-wide. To change the roles of an existing member, [assign and revoke roles](/docs/iam/assign-roles).

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

<BeforeYouBegin>

- To invite, remove or cancel an invite: an org-wide `roles/owner` assignment. You can only invite with a role you could assign yourself, and only remove a member whose every role you could revoke. See [Who can assign a role](/docs/iam/access-model#who-can-assign-a-role).
- To list members and invites: an org-wide `roles/owner`, `roles/viewer` or `roles/iam/editor` assignment.
- Your organization ID (`<org-id>`).

</BeforeYouBegin>

## Invite a member [#invite-a-member]

1. Find the URN of the role the new member should get with `list-roles`. See [Built-in roles](/docs/iam/roles).
1. Send the invite:

   ```sh
   origin iam invite-member --org-id <org-id> \
     --email jane@example.com \
     --role-urn urn:origin:cloud:iam::::tc/role/roles/viewer
   ```

   - Account exists: the role is granted org-wide immediately. There’s no separate step to accept.
   - No account yet: the invite is stored as pending. It’s applied the first time that address signs up and signs in to the console, or reads its own identity with `origin iam current-user`. If by then you can no longer assign the role yourself, the invite is dropped instead.
1. Verify the invite. An existing account appears in the member list; a pending invite appears in the invite list.

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

Invites are org-wide only. To give someone access to a single project, ask them to sign up and send you the `userId` that `origin iam current-user` shows them. Then assign a project-scoped role to `user:<user-id>`.

## List members and invites [#list-members-and-invites]

- `list-members` shows every principal with an active role assignment, at any scope, with all of its role URNs. For users, it includes the name and email address where the platform can resolve them. Service accounts with roles appear here too.
- `principal-grants` shows one principal’s role assignments, each with its project scope.
- `list-invites` shows pending invites: the ID, email address, role URN, who invited them and when. An invite disappears from the list once it’s applied or canceled.

## Remove a member [#remove-a-member]

Removing a member revokes every role the principal holds in the organization, org-wide and in every project. To take away a single role, [revoke the role](/docs/iam/assign-roles#revoke-a-role) instead.

1. Find the member’s principal in the output of `list-members`.
1. Remove the member.

   ```sh
   origin iam remove-member --org-id <org-id> --principal user:<user-id>
   ```

1. Run `list-members` again and check that the principal is gone.

Removing a principal that holds no roles succeeds and changes nothing. If the member is the organization’s last org-wide owner, the platform refuses with `CONFLICT` and removes nothing. See [The last owner is protected](/docs/iam/access-model#the-last-owner-is-protected). If the member holds a role you couldn’t revoke yourself, such as a billing role when you hold none, the platform refuses with `FORBIDDEN` and removes nothing.

## Cancel a pending invite [#cancel-a-pending-invite]

`remove-member` acts only on role assignments, so it doesn’t cancel a pending invite.

1. Find the invite’s ID with `list-invites`.
1. Cancel the invite.

   ```sh
   origin iam revoke-invite --org-id <org-id> --invite-id <invite-id>
   ```

1. Run `list-invites` again and check that the invite is gone.

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

The mutations are `inviteMember`, `removeMember` and `revokeInvite`; the queries are `orgMembers` and `orgInvites`, all in the `iam` namespace. `orgRoleAssignments` returns the same data as `orgMembers` with one entry per assignment, including its project scope and when it was created. For the full list, see the [IAM reference](/docs/iam/reference).

```graphql
mutation {
  iam {
    inviteMember(input: {
      orgId: "<org-id>"
      email: "jane@example.com"
      roleUrn: "urn:origin:cloud:iam::::tc/role/roles/viewer"
    })
  }
}
```

## Related [#related]

- [Assign and revoke roles](/docs/iam/assign-roles)
- [Access model](/docs/iam/access-model)
- [Organizations](/docs/platform/organizations)
- [Audit log](/docs/iam/audit-log) – invites, cancellations and removals are recorded