> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/products/iam/api-reference.md). # IAM API reference How the IAM reference is organized: one page each for roles, for what a role grants, and for who holds a role, and how the IAM lists paginate. The IAM API reference documents the operations and types that Navixy GraphQL API exposes from IAM, the identity and access management service of the platform: the roles of your organization, what each role grants, and who holds it. Each page covers its queries and mutations, its object and input types, and its enums, with a field table for every type. The reference states what each operation and field is. For the GraphQL fundamentals behind the notation, see [GraphQL basics](/docs/navixy-graphql-api/graphql-basics.md), including the [type syntax](/docs/navixy-graphql-api/graphql-basics.md#type-syntax) that the field tables use. ## Where the operations live All IAM queries are nested under the `iam` field of the `Query` type, and the IAM mutations under the `iam` field of the `Mutation` type. Every response has the same shape under `data.iam`. Every operation acts in the organization and the workspace that your [access token](/docs/navixy-graphql-api/authentication.md) names, so no field takes an organization ID or a workspace ID. A token that names no organization or no workspace is refused with `PERMISSION_DENIED`. A role of another organization is out of reach: `role` returns null for it, and [`memberRoleAssign`](/docs/navixy-graphql-api/products/iam/api-reference/role-assignments.md#memberroleassign) refuses it with `CONFLICT`. IAM decides what you may do. To call any `iam` operation, you need a role that grants product `iam` or every product. The Owner role grants every product, and so does the Admin role as IAM creates it. You can't create, change, delete, assign, or revoke a role that grants more than your own roles do. IAM refuses such a request with `PERMISSION_DENIED` and `dependencyCode` `GRANT_CEILING_EXCEEDED`. The same refusal applies to an assignment that would last longer than your own access to the role, so a permanent assignment needs your own access to be permanent. A role that you couldn't have granted can't be changed, not even narrowed. A role that grants every workspace, every product, or every feature or data resource of a product needs a caller whose own roles grant the same. A list that happens to name every item doesn't count as "every". ## Pages
PageCovers
RolesIamRole with its connection and edge types, the roles, role, and workspaceRoles queries, and the roleCreate, roleUpdate, and roleDelete mutations with their inputs and payloads.
Role accessWhat a role grants: IamSelection for the workspaces it reaches, and the product scopes, features, and data resources it covers (IamRoleProductScopes, IamRoleProductScope, IamRoleDataResources, IamRoleDataResourceGrant, IamRoleItemActions), with the input type for each.
Role assignmentsIamMemberRoleAssignment, IamRoleHolder, and IamRolePrincipalType, the memberRoles and roleHolders queries, and the memberRoleAssign and memberRoleRevoke mutations with their inputs and payloads.
## How these lists paginate The two IAM connections page differently, and both differ from the [pagination](/docs/navixy-graphql-api/pagination.md) the other products use: * `roles` pages in both directions. `first` and `after` page forward. `last` pages backward only together with `before`, and `before` is only valid together with `last`. The API answers `VALIDATION_ERROR` when these rules are broken. * `roles` is ordered by role ID, and the cursor of each edge is the role ID. `total` is exact and counts inactive roles too. * `roleHolders` pages forward only. `last` and `before` are refused with `VALIDATION_ERROR`, and `total` is always null. For the number of holders, read `IamRole.holderCount`. * The default page size is 50, and `first` and `last` accept 1 to 100. The default of 20 on the general [Pagination](/docs/navixy-graphql-api/pagination.md) page doesn't apply here. `workspaceRoles` and `memberRoles` return plain lists, not connections. ## Identifiers `IamRole.id` and every `roleId` are `ID` values that IAM issues. A `roleId` issued in another Navixy region or deployment is refused with `VALIDATION_ERROR`. `IamRole` isn't a `Node`, so `node(id:)` doesn't return it. Read a role through `role` or `roles`. Role titles aren't unique, so identify a role by its ID. `IamRole.organizationId` is an `ID`, the same value as `ConsoleOrganization.id` in [Console](/docs/navixy-graphql-api/products/console/api-reference/organizations.md). For this ID, `node(id:)` returns the organization when it's one of your own organizations. If IAM returns a role whose `organizationId` isn't an organization ID, the operation that returns the role fails with `SERVICE_UNAVAILABLE` and `dependency: "iam"`. `actorId` is a `UUID` that Navixy Console issues for a person or an integration. Your own actor ID is the `actor_id` claim of your [access token](/docs/navixy-graphql-api/authentication.md#access-token-claims). To find the actor ID of another member, read [members](/docs/navixy-graphql-api/products/console/api-reference/members.md#members) in Console. `productCode` in `IamRoleProductScope` and `IamRoleProductScopeInput`, and `resourceType` in `IamRoleDataResourceGrant` and `IamRoleDataResourceGrantInput`, are [`Code`](/docs/navixy-graphql-api/core-api-reference/common.md#code) values. An input with a value that isn't a valid code is refused before the request runs, as a `VALIDATION_ERROR` without a `field`. ## Refusals relayed from IAM The `iam` operations call IAM, and IAM checks every request itself. When IAM refuses a request, the API answers with the matching [error code](/docs/navixy-graphql-api/error-handling.md#error-codes) and marks the error with `dependency: "iam"`. `dependencyCode` holds IAM's own reason, such as `GRANT_CEILING_EXCEEDED`, `NOT_A_MEMBER`, or `LAST_OWNER`. `entityType` is `IamMemberRoleAssignment` on `memberRoles` and `memberRoleRevoke`, and `IamRole` on the other operations. `entityId` holds the role ID when the request named a role. ## Shared types The interfaces and pagination types that IAM shares with the other products are on the [Common resources](/docs/navixy-graphql-api/core-api-reference/common.md) page. The [Core API reference](/docs/navixy-graphql-api/core-api-reference.md) indexes the reference pages of every product. ## Other ways to explore the API * [Public GraphQL schema](/docs/navixy-graphql-api/developer-resources/public-graphql-schema.md): The full type system split into several files. * [Introspection](/docs/navixy-graphql-api/graphql-basics.md#introspection): Explore the schema from your own GraphQL client. ## See also * [Authentication](/docs/navixy-graphql-api/authentication.md): Learn how the access token names the organization and the workspace that every request acts in. * [Error handling](/docs/navixy-graphql-api/error-handling.md): Understand error structure, codes, and common error scenarios. * [Optimistic locking](/docs/navixy-graphql-api/optimistic-locking.md): Pass the `version` you last read to `roleUpdate` and `roleDelete`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://navixy.com/docs/navixy-graphql-api/products/iam/api-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.