# IAM reference

Where to find every origin iam command and built-in role, and a one-line summary of each IAM query and mutation in the GraphQL API.

Look up exact commands, roles and API operations here. For how IAM works, see [Access model](/docs/iam/access-model).

## Reference pages [#reference-pages]

| Page | What it lists |
| --- | --- |
| [CLI commands](/docs/iam/reference/cli) | Every `origin iam` command with its options. See [`origin iam` commands](/docs/iam/reference/cli). |
| [Built-in roles](/docs/iam/roles) | Every role with its URN and permissions. See [Built-in roles](/docs/iam/roles). |
| [Errors](/docs/platform/reference/errors) | Error codes shared by every API operation. See [Errors](/docs/platform/reference/errors). |

## GraphQL queries [#graphql-queries]

All queries are fields of the `iam` namespace of the query root.

| Query | Returns |
| --- | --- |
| `currentUser` | The signed-in user. |
| `currentUserGrants` | Every role assignment the caller holds, in all organizations. |
| `principalGrants` | Every role assignment one principal holds in the organization, with its scope and creation time. Needs `iam.member.list`, like `orgRoleAssignments`. |
| `roles` | Every built-in role with its permissions. |
| `role` | One built-in role by the URN `roles` lists. Needs no permission. |
| `groups` | The three built-in groups, by name and description. Groups aren’t principals and can’t hold roles. |
| `group` | One built-in group by URN, with your organization ID in it: `urn:origin:cloud:iam::<org-id>::tc/group/<group-id>`. |
| `permissions` | Every permission the platform defines. |
| `hasPermission` | Whether a principal holds a permission on a resource. |
| `orgMembers` | Every principal with a role assignment in the organization, with its role URNs. |
| `orgRoleAssignments` | Every role assignment in the organization, with its scope and creation time. |
| `orgInvites` | Pending invites in the organization. |
| `serviceAccounts` | Every service account in the organization, active or revoked, without secrets. |
| `auditLogEntries` | One page of the organization’s audit log. See [Audit log](/docs/iam/audit-log). |

## GraphQL mutations [#graphql-mutations]

All mutations are fields of the `iam` namespace of the mutation root.

| Mutation | Effect |
| --- | --- |
| `assignRole` | Assigns a built-in role to a principal, org-wide or for one project. Only a role whose permissions you hold yourself at that scope. |
| `revokeRole` | Revokes one role from a principal at exactly the given scope. Only a role whose permissions you hold yourself at that scope. |
| `inviteMember` | Invites a person by email with one org-wide role, which you must be able to assign. |
| `removeMember` | Revokes every role a principal holds in the organization, if you could revoke each of them. |
| `revokeInvite` | Cancels a pending invite. |
| `createServiceAccount` | Creates a service account and returns its client ID and one-time client secret. |
| `revokeServiceAccount` | Disables a service account’s credential. |

## Example: list one principal’s grants [#example-list-one-principals-grants]

`principalGrants` takes its arguments in an `input` object with `orgId` and `principal`. This form replaced a bare `principal` argument on 12 October 2026, without a deprecation period. A grant whose `projectId` is `null` is org-wide.

```graphql
query {
  iam {
    principalGrants(input: {
      orgId: "<org-id>"
      principal: "user:<user-id>"
    }) {
      urn
      projectId
      roles {
        roleUrn
      }
      createdAt
      createdBy
    }
  }
}
```

The CLI equivalent is `origin iam principal-grants --org-id <org-id> --principal <principal>`.