> 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.md). # IAM overview IAM holds the roles of your organization. The API lets you view, create, and change roles, and assign them to members or revoke them. **IAM API** (identity and access management) is the product that decides who may do what in your organization. It's one of the products served by [Navixy GraphQL API](/docs/navixy-graphql-api/readme.md). IAM stores the organization's roles, what each role gives access to, and who holds each role. This documentation is for Navixy users who call the API for their own organization to set up roles and assign them to members. All IAM queries are nested under the `iam` field of the `Query` type and IAM mutations under the `iam` field of the `Mutation` type. Authentication and error handling work the same way for every product of Navixy GraphQL API, so see [Authentication](/docs/navixy-graphql-api/authentication.md) and [Error handling](/docs/navixy-graphql-api/error-handling.md) to learn that. IAM lists are paged differently from the other products: see [How these lists paginate](/docs/navixy-graphql-api/products/iam/api-reference.md#how-these-lists-paginate). For the endpoint and request headers, see [Getting started](/docs/navixy-graphql-api/getting-started.md). ## Purpose and capabilities IAM API enables you to: * View the roles of your organization and the roles you can assign in your workspace * Create a role, change what it gives access to, and delete it * See which roles a member holds and who holds a role * Assign a role to a member, permanently or until a set time, and revoke it Your access token names one of your organizations and one of its workspaces. IAM works with the roles of that organization. To work with the roles of another organization, you need a token issued for it. ## Key concepts
TermDefinition
RoleA named set of access rights in one organization. It grants no access rights in the organization's child organizations. A role is active or inactive. An inactive role continues to exist but grants no access. Its assignments remain and resume working once the role is active.
Owner roleThe role that IAM creates for every organization. It gives access to everything in the organization. It can't be changed, deleted, or assigned through the API, and IAM won't revoke it from its last holder.
Workspace reachThe workspaces of the organization where a role applies: all of them, including the ones created later, or only the ones you pick.
Product accessThe products a role gives access to. For each product, a role gives access to all of it, or only to some of its features and data resources.
Data resourceA kind of data inside a product. A role can give access to all items of that kind or only to some, and set which actions are allowed on each item.
MemberA person or an integration that belongs to the organization in Navixy Console. Only a member can be assigned a role. The API identifies a member by an actor ID issued by Navixy Console. Your own actor ID is in your access token, and the actor IDs of the other members come from the members query of Console.
Role assignmentA role that a member holds. An assignment is permanent or ends at a set time.
## How roles work in an organization 1. Navixy Console creates the organization, and IAM creates its Owner role and assigns it to the person who created the organization. 2. Someone with access to IAM creates the roles the organization needs. Each role sets the workspaces where it applies and the products it gives access to. 3. They assign roles to members. A role can be assigned only while it's active, and only in a workspace where it applies. 4. To change a role, you send the whole role again. If someone else changed the role after you read it, IAM refuses the change, so read the role again and repeat the change. 5. Revoking a role ends the assignment. Deleting a role revokes it from everyone who holds it. ## Who does what Three parties share the work on roles:
WhoDoes
YouView the roles and who holds them, create, change, and delete roles, and assign or revoke roles. You can't give anyone more access than your own roles give you.
IAMCreates the Owner role of each organization and protects it. Checks every request against your own roles before it makes a change.
Navixy ConsoleKeeps the list of members of each organization, which you can read through its members query. IAM refuses to assign a role to anyone who isn't on that list.
To use the IAM API, you need a role that gives access to IAM in your organization. The Owner role always has it. Note two behaviors of the IAM API. The list of the holders of a role also includes people who have left the organization or never joined it. A role that you have just created or changed can take about a second to appear among the roles you can assign. ## Navigation The IAM documentation has an API reference with one page per topic. The [IAM API reference](/docs/navixy-graphql-api/products/iam/api-reference.md) documents the operations and types, explains how IAM lists are paged, and lists the refusals that come from IAM: * [Roles](/docs/navixy-graphql-api/products/iam/api-reference/roles.md) documents the roles of your organization and the changes that create, replace, and delete a role. * [Role access](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md) documents what a role gives access to: workspaces, products, features, and data resources. * [Role assignments](/docs/navixy-graphql-api/products/iam/api-reference/role-assignments.md) documents who holds which role and the changes that assign and revoke a role. For the types that IAM shares with the other products and for an index of the whole API, see [Core API reference](/docs/navixy-graphql-api/core-api-reference.md). {% hint style="warning" %} The API supports [GraphQL introspection](/docs/navixy-graphql-api/graphql-basics.md#introspection) for authenticated users. You can also check the public [GraphQL schema](/docs/navixy-graphql-api/developer-resources/public-graphql-schema.md). {% endhint %} --- # 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.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.