> 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/roles.md).
# Roles
Reference for the roles of your organization: the roles, role, and workspaceRoles queries, the roleCreate, roleUpdate, and roleDelete mutations, and the IamRole type with its connection.
The roles of the caller's organization, the roles that can be assigned in the caller's workspace, and the mutations that create, replace, and delete a role.
## Queries
### roles
The roles of the caller's organization, inactive ones included, ordered by id.
```graphql
roles(
first: Int
after: String
last: Int
before: String
): IamRoleConnection!
```
**Arguments**
| Name | Type | Description |
| -------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `first` | `Int` | The first `n` elements from the [paginated list](/docs/navixy-graphql-api/pagination.md). |
| `after` | `String` | The elements that come after the specified [cursor](/docs/navixy-graphql-api/pagination.md). |
| `last` | `Int` | The last `n` elements from the [paginated list](/docs/navixy-graphql-api/pagination.md). Requires `before`. |
| `before` | `String` | The elements that come before the specified [cursor](/docs/navixy-graphql-api/pagination.md). Requires `last`. |
**Output types:**
IamRoleConnection
A page of the roles of the caller's organization.
**Implements:** [Connection](/docs/navixy-graphql-api/core-api-reference/common.md#connection)
| Field | Type | Description |
| ---------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `edges` | \[[IamRoleEdge](#iamroleedge)!]! | |
| `nodes` | \[[IamRole](#iamrole)!]! | |
| `pageInfo` | [PageInfo](/docs/navixy-graphql-api/core-api-reference/common.md#pageinfo)! | Information about the current page. |
| `total` | [CountInfo](/docs/navixy-graphql-api/core-api-reference/common.md#countinfo) | The number of roles in the caller's organization, inactive ones included. |
***
### role
One role of the caller's organization. Null when IAM has no such role there, or it was deleted.
```graphql
role(
id: ID!
): IamRole
```
**Arguments**
| Name | Type | Description |
| ---- | ----- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `ID!` | The role ID, as IAM issued it. `IamRole` isn't a `Node`, so `node(id:)` doesn't return a role: read it with `role` or `roles`. |
**Output types:**
IamRole
A role of the caller's organization. A role belongs to one organization and reaches no other.
| Field | Type | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The role ID, as IAM issued it. `IamRole` isn't a `Node`, so `node(id:)` doesn't return a role: read it with `role` or `roles`. |
| `organizationId` | `ID!` | The organization the role belongs to: the same value as `ConsoleOrganization.id`. |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Null when it has none. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. An inactive role is stored but grants nothing. |
| `isSystem` | `Boolean!` | Whether IAM provisioned and protects the role: the organization's Owner. `roleUpdate` and `roleDelete` refuse such a role with CONFLICT. |
| `version` | `Int!` | The version number for optimistic locking. Pass it to `roleUpdate` and `roleDelete`. |
| `workspaces` | [IamSelection](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselection)! | The workspaces of the organization the role reaches, by workspace ID. It's empty when Navixy Console has deleted every workspace that the role named. Such a role reaches nothing, and `roleUpdate` accepts it only with a workspace named again. |
| `productScopes` | [IamRoleProductScopes](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopes)! | The products the role grants. |
| `holderCount` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long)! | How many actors hold the role now, as IAM counts them: every principal type and every holder whose assignment has not expired, including people who have since left the organization or were invited and never joined. IAM holds assignments, not memberships. It can therefore be larger than the number of members a member list shows. 0 for an inactive role, which IAM does not count. |
***
### workspaceRoles
The active roles that can be assigned in the caller's workspace, ordered by id. A role created or changed moments ago can be missing for about a second.
```graphql
workspaceRoles: [IamRole!]!
```
**Output types:**
IamRole
A role of the caller's organization. A role belongs to one organization and reaches no other.
| Field | Type | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The role ID, as IAM issued it. `IamRole` isn't a `Node`, so `node(id:)` doesn't return a role: read it with `role` or `roles`. |
| `organizationId` | `ID!` | The organization the role belongs to: the same value as `ConsoleOrganization.id`. |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Null when it has none. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. An inactive role is stored but grants nothing. |
| `isSystem` | `Boolean!` | Whether IAM provisioned and protects the role: the organization's Owner. `roleUpdate` and `roleDelete` refuse such a role with CONFLICT. |
| `version` | `Int!` | The version number for optimistic locking. Pass it to `roleUpdate` and `roleDelete`. |
| `workspaces` | [IamSelection](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselection)! | The workspaces of the organization the role reaches, by workspace ID. It's empty when Navixy Console has deleted every workspace that the role named. Such a role reaches nothing, and `roleUpdate` accepts it only with a workspace named again. |
| `productScopes` | [IamRoleProductScopes](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopes)! | The products the role grants. |
| `holderCount` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long)! | How many actors hold the role now, as IAM counts them: every principal type and every holder whose assignment has not expired, including people who have since left the organization or were invited and never joined. IAM holds assignments, not memberships. It can therefore be larger than the number of members a member list shows. 0 for an inactive role, which IAM does not count. |
***
## Mutations
### roleCreate
Creates a role in the caller's organization.
```graphql
roleCreate(
input: IamRoleCreateInput!
): IamRolePayload
```
**Arguments**
| Name | Type | Description |
| ------- | --------------------- | ---------------------------------- |
| `input` | `IamRoleCreateInput!` | The input fields for the new role. |
**Input types:**
IamRoleCreateInput
A new role, homed in the caller's organization. IAM refuses a role granting more than the caller's own roles do with PERMISSION\_DENIED, `dependencyCode` GRANT\_CEILING\_EXCEEDED.
| Field | Type | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Omitted or null for none. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. |
| `workspaces` | [IamSelectionInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselectioninput)! | The workspaces of the organization the role reaches, by workspace ID. IAM refuses an empty selection and a workspace that the organization doesn't own. It checks the grant ceiling first and treats an empty selection as every workspace. So a caller whose own roles don't reach every workspace, or don't reach the named one, gets `PERMISSION_DENIED` with `dependencyCode` `GRANT_CEILING_EXCEEDED`. Any other caller gets `VALIDATION_ERROR`. |
| `productScopes` | [IamRoleProductScopesInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopesinput)! | The products the role grants. |
IamSelectionInput
A selection to store: every current and future item when `all` is true, exactly `items` otherwise.
| Field | Type | Description |
| ------- | ------------ | ------------------------------------------------------------------------------ |
| `all` | `Boolean!` | Whether every current and future item is selected. `items` must then be empty. |
| `items` | `[String!]!` | The selected items when `all` is false. |
IamRoleProductScopesInput
The products to grant.
| Field | Type | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `all` | `Boolean!` | Whether to grant every product. `specific` must then be empty. |
| `specific` | \[[IamRoleProductScopeInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopeinput)!]! | One scope per product when `all` is false. |
IamRoleProductScopeInput
What to grant within one product.
| Field | Type | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `productCode` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | IAM's code for the product. At most once per role. |
| `features` | [IamSelectionInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselectioninput)! | The features to grant, by feature code. |
| `dataResources` | [IamRoleDataResourcesInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroledataresourcesinput)! | The data resources to grant. |
IamRoleDataResourcesInput
The data resources to grant within one product.
| Field | Type | Description |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `all` | `Boolean!` | Whether to grant every data resource of the product. `byType` must then be empty. |
| `byType` | \[[IamRoleDataResourceGrantInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroledataresourcegrantinput)!]! | One grant per data-resource type when `all` is false. |
IamRoleDataResourceGrantInput
What to grant on one data-resource type of a product.
| Field | Type | Description |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `resourceType` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | IAM's code for the data-resource type. At most once per product. |
| `items` | [IamSelectionInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselectioninput)! | The items of this type to cover. |
| `actions` | `[String!]!` | The actions to grant on every covered item, unless `itemActions` names the item. |
| `itemActions` | \[[IamRoleItemActionsInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleitemactionsinput)!]! | Per-item overrides. |
IamRoleItemActionsInput
The actions to grant on one data-resource item, in place of its grant's `actions`.
| Field | Type | Description |
| --------- | ------------ | ------------------------------------------------------------ |
| `itemId` | `String!` | IAM's id for the data-resource item. At most once per grant. |
| `actions` | `[String!]!` | The actions to grant on this item. |
**Output types:**
IamRolePayload
The role as IAM stored it.
| Field | Type | Description |
| ------ | -------------------- | -------------------------------------------------- |
| `role` | [IamRole](#iamrole)! | The role as IAM answered the write, not read back. |
IamRole (entity)
A role of the caller's organization. A role belongs to one organization and reaches no other.
| Field | Type | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The role ID, as IAM issued it. `IamRole` isn't a `Node`, so `node(id:)` doesn't return a role: read it with `role` or `roles`. |
| `organizationId` | `ID!` | The organization the role belongs to: the same value as `ConsoleOrganization.id`. |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Null when it has none. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. An inactive role is stored but grants nothing. |
| `isSystem` | `Boolean!` | Whether IAM provisioned and protects the role: the organization's Owner. `roleUpdate` and `roleDelete` refuse such a role with CONFLICT. |
| `version` | `Int!` | The version number for optimistic locking. Pass it to `roleUpdate` and `roleDelete`. |
| `workspaces` | [IamSelection](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselection)! | The workspaces of the organization the role reaches, by workspace ID. It's empty when Navixy Console has deleted every workspace that the role named. Such a role reaches nothing, and `roleUpdate` accepts it only with a workspace named again. |
| `productScopes` | [IamRoleProductScopes](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopes)! | The products the role grants. |
| `holderCount` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long)! | How many actors hold the role now, as IAM counts them: every principal type and every holder whose assignment has not expired, including people who have since left the organization or were invited and never joined. IAM holds assignments, not memberships. It can therefore be larger than the number of members a member list shows. 0 for an inactive role, which IAM does not count. |
***
### roleUpdate
Replaces a role's whole document: every field of the input replaces the stored one. See `IamRoleUpdateInput`.
```graphql
roleUpdate(
input: IamRoleUpdateInput!
): IamRolePayload
```
**Arguments**
| Name | Type | Description |
| ------- | --------------------- | --------------------------------------------- |
| `input` | `IamRoleUpdateInput!` | The input fields for the role's new document. |
**Input types:**
IamRoleUpdateInput
The whole new document of a role: every field replaces the stored one, so an omitted description removes it and an empty list empties it. There is no partial update. Refused with `CONFLICT` when `version` isn't the stored one, or when the role is a system role. Refused with `PERMISSION_DENIED` and `dependencyCode` `GRANT_CEILING_EXCEEDED` when the role as stored or as written grants more than your own roles do, so you can't change a role that you couldn't have granted, not even to narrow it. The same refusal applies when the role has holders and the change adds access that your own roles don't cover until the last holder's assignment ends.
| Field | Type | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The role to replace. |
| `version` | `Int!` | The role's version as last read. |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Omitted or null removes it. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. |
| `workspaces` | [IamSelectionInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselectioninput)! | The workspaces of the organization the role reaches, by workspace ID. IAM refuses an empty selection and a workspace that the organization doesn't own. It checks the grant ceiling first and treats an empty selection as every workspace. So a caller whose own roles don't reach every workspace, or don't reach the named one, gets `PERMISSION_DENIED` with `dependencyCode` `GRANT_CEILING_EXCEEDED`. Any other caller gets `VALIDATION_ERROR`. |
| `productScopes` | [IamRoleProductScopesInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopesinput)! | The products the role grants. |
IamSelectionInput
A selection to store: every current and future item when `all` is true, exactly `items` otherwise.
| Field | Type | Description |
| ------- | ------------ | ------------------------------------------------------------------------------ |
| `all` | `Boolean!` | Whether every current and future item is selected. `items` must then be empty. |
| `items` | `[String!]!` | The selected items when `all` is false. |
IamRoleProductScopesInput
The products to grant.
| Field | Type | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `all` | `Boolean!` | Whether to grant every product. `specific` must then be empty. |
| `specific` | \[[IamRoleProductScopeInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopeinput)!]! | One scope per product when `all` is false. |
IamRoleProductScopeInput
What to grant within one product.
| Field | Type | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `productCode` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | IAM's code for the product. At most once per role. |
| `features` | [IamSelectionInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselectioninput)! | The features to grant, by feature code. |
| `dataResources` | [IamRoleDataResourcesInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroledataresourcesinput)! | The data resources to grant. |
IamRoleDataResourcesInput
The data resources to grant within one product.
| Field | Type | Description |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `all` | `Boolean!` | Whether to grant every data resource of the product. `byType` must then be empty. |
| `byType` | \[[IamRoleDataResourceGrantInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroledataresourcegrantinput)!]! | One grant per data-resource type when `all` is false. |
IamRoleDataResourceGrantInput
What to grant on one data-resource type of a product.
| Field | Type | Description |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `resourceType` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | IAM's code for the data-resource type. At most once per product. |
| `items` | [IamSelectionInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselectioninput)! | The items of this type to cover. |
| `actions` | `[String!]!` | The actions to grant on every covered item, unless `itemActions` names the item. |
| `itemActions` | \[[IamRoleItemActionsInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleitemactionsinput)!]! | Per-item overrides. |
IamRoleItemActionsInput
The actions to grant on one data-resource item, in place of its grant's `actions`.
| Field | Type | Description |
| --------- | ------------ | ------------------------------------------------------------ |
| `itemId` | `String!` | IAM's id for the data-resource item. At most once per grant. |
| `actions` | `[String!]!` | The actions to grant on this item. |
**Output types:**
IamRolePayload
The role as IAM stored it.
| Field | Type | Description |
| ------ | -------------------- | -------------------------------------------------- |
| `role` | [IamRole](#iamrole)! | The role as IAM answered the write, not read back. |
IamRole (entity)
A role of the caller's organization. A role belongs to one organization and reaches no other.
| Field | Type | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The role ID, as IAM issued it. `IamRole` isn't a `Node`, so `node(id:)` doesn't return a role: read it with `role` or `roles`. |
| `organizationId` | `ID!` | The organization the role belongs to: the same value as `ConsoleOrganization.id`. |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Null when it has none. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. An inactive role is stored but grants nothing. |
| `isSystem` | `Boolean!` | Whether IAM provisioned and protects the role: the organization's Owner. `roleUpdate` and `roleDelete` refuse such a role with CONFLICT. |
| `version` | `Int!` | The version number for optimistic locking. Pass it to `roleUpdate` and `roleDelete`. |
| `workspaces` | [IamSelection](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselection)! | The workspaces of the organization the role reaches, by workspace ID. It's empty when Navixy Console has deleted every workspace that the role named. Such a role reaches nothing, and `roleUpdate` accepts it only with a workspace named again. |
| `productScopes` | [IamRoleProductScopes](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopes)! | The products the role grants. |
| `holderCount` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long)! | How many actors hold the role now, as IAM counts them: every principal type and every holder whose assignment has not expired, including people who have since left the organization or were invited and never joined. IAM holds assignments, not memberships. It can therefore be larger than the number of members a member list shows. 0 for an inactive role, which IAM does not count. |
***
### roleDelete
Deletes a role and every assignment of it.
```graphql
roleDelete(
input: IamRoleDeleteInput!
): IamRoleDeletePayload
```
**Arguments**
| Name | Type | Description |
| ------- | --------------------- | ---------------------------------------- |
| `input` | `IamRoleDeleteInput!` | The input fields for the role to delete. |
**Input types:**
IamRoleDeleteInput
A role to delete. Refused with `CONFLICT` when `version` isn't the stored one, or when the role is a system role. Refused with `PERMISSION_DENIED` and `dependencyCode` `GRANT_CEILING_EXCEEDED` when you couldn't have granted the role. Deleting a role also revokes every assignment of it.
| Field | Type | Description |
| --------- | ------ | -------------------------------- |
| `id` | `ID!` | The role to delete. |
| `version` | `Int!` | The role's version as last read. |
**Output types:**
IamRoleDeletePayload
The result of deleting a role.
| Field | Type | Description |
| ----------- | ----- | --------------------------- |
| `deletedId` | `ID!` | The id of the deleted role. |
***
## Objects
### IamRole
A role of the caller's organization. A role belongs to one organization and reaches no other.
| Field | Type | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The role ID, as IAM issued it. `IamRole` isn't a `Node`, so `node(id:)` doesn't return a role: read it with `role` or `roles`. |
| `organizationId` | `ID!` | The organization the role belongs to: the same value as `ConsoleOrganization.id`. |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Null when it has none. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. An inactive role is stored but grants nothing. |
| `isSystem` | `Boolean!` | Whether IAM provisioned and protects the role: the organization's Owner. `roleUpdate` and `roleDelete` refuse such a role with CONFLICT. |
| `version` | `Int!` | The version number for optimistic locking. Pass it to `roleUpdate` and `roleDelete`. |
| `workspaces` | [IamSelection](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselection)! | The workspaces of the organization the role reaches, by workspace ID. It's empty when Navixy Console has deleted every workspace that the role named. Such a role reaches nothing, and `roleUpdate` accepts it only with a workspace named again. |
| `productScopes` | [IamRoleProductScopes](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopes)! | The products the role grants. |
| `holderCount` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long)! | How many actors hold the role now, as IAM counts them: every principal type and every holder whose assignment has not expired, including people who have since left the organization or were invited and never joined. IAM holds assignments, not memberships. It can therefore be larger than the number of members a member list shows. 0 for an inactive role, which IAM does not count. |
***
### IamRolePayload
The role as IAM stored it.
| Field | Type | Description |
| ------ | -------------------- | -------------------------------------------------- |
| `role` | [IamRole](#iamrole)! | The role as IAM answered the write, not read back. |
***
### IamRoleDeletePayload
The result of deleting a role.
| Field | Type | Description |
| ----------- | ----- | --------------------------- |
| `deletedId` | `ID!` | The id of the deleted role. |
***
## Inputs
### IamRoleCreateInput
A new role, homed in the caller's organization. IAM refuses a role granting more than the caller's own roles do with PERMISSION\_DENIED, `dependencyCode` GRANT\_CEILING\_EXCEEDED.
| Field | Type | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Omitted or null for none. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. |
| `workspaces` | [IamSelectionInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselectioninput)! | The workspaces of the organization the role reaches, by workspace ID. IAM refuses an empty selection and a workspace that the organization doesn't own. It checks the grant ceiling first and treats an empty selection as every workspace. So a caller whose own roles don't reach every workspace, or don't reach the named one, gets `PERMISSION_DENIED` with `dependencyCode` `GRANT_CEILING_EXCEEDED`. Any other caller gets `VALIDATION_ERROR`. |
| `productScopes` | [IamRoleProductScopesInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopesinput)! | The products the role grants. |
***
### IamRoleUpdateInput
The whole new document of a role: every field replaces the stored one, so an omitted description removes it and an empty list empties it. There is no partial update. Refused with `CONFLICT` when `version` isn't the stored one, or when the role is a system role. Refused with `PERMISSION_DENIED` and `dependencyCode` `GRANT_CEILING_EXCEEDED` when the role as stored or as written grants more than your own roles do, so you can't change a role that you couldn't have granted, not even to narrow it. The same refusal applies when the role has holders and the change adds access that your own roles don't cover until the last holder's assignment ends.
| Field | Type | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The role to replace. |
| `version` | `Int!` | The role's version as last read. |
| `title` | `String!` | The role's name. |
| `description` | `String` | The role's description. Omitted or null removes it. |
| `isActive` | `Boolean!` | Whether the role can be assigned and grants anything. |
| `workspaces` | [IamSelectionInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamselectioninput)! | The workspaces of the organization the role reaches, by workspace ID. IAM refuses an empty selection and a workspace that the organization doesn't own. It checks the grant ceiling first and treats an empty selection as every workspace. So a caller whose own roles don't reach every workspace, or don't reach the named one, gets `PERMISSION_DENIED` with `dependencyCode` `GRANT_CEILING_EXCEEDED`. Any other caller gets `VALIDATION_ERROR`. |
| `productScopes` | [IamRoleProductScopesInput](/docs/navixy-graphql-api/products/iam/api-reference/role-access.md#iamroleproductscopesinput)! | The products the role grants. |
***
### IamRoleDeleteInput
A role to delete. Refused with `CONFLICT` when `version` isn't the stored one, or when the role is a system role. Refused with `PERMISSION_DENIED` and `dependencyCode` `GRANT_CEILING_EXCEEDED` when you couldn't have granted the role. Deleting a role also revokes every assignment of it.
| Field | Type | Description |
| --------- | ------ | -------------------------------- |
| `id` | `ID!` | The role to delete. |
| `version` | `Int!` | The role's version as last read. |
***
## Pagination types
### IamRoleConnection
A page of the roles of the caller's organization.
**Implements:** [Connection](/docs/navixy-graphql-api/core-api-reference/common.md#connection)
| Field | Type | Description |
| ---------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `edges` | \[[IamRoleEdge](#iamroleedge)!]! | |
| `nodes` | \[[IamRole](#iamrole)!]! | |
| `pageInfo` | [PageInfo](/docs/navixy-graphql-api/core-api-reference/common.md#pageinfo)! | Information about the current page. |
| `total` | [CountInfo](/docs/navixy-graphql-api/core-api-reference/common.md#countinfo) | The number of roles in the caller's organization, inactive ones included. |
***
### IamRoleEdge
An edge in an IamRoleConnection.
**Implements:** [Edge](/docs/navixy-graphql-api/core-api-reference/common.md#edge)
| Field | Type | Description |
| -------- | -------------------- | ------------------------------- |
| `cursor` | `String!` | An opaque cursor for this edge. |
| `node` | [IamRole](#iamrole)! | |
***
## See also
* [Pagination](/docs/navixy-graphql-api/pagination.md)
* [Error handling](/docs/navixy-graphql-api/error-handling.md)
* [Optimistic locking](/docs/navixy-graphql-api/optimistic-locking.md)
* [Limits](/docs/navixy-graphql-api/limits.md)
---
# 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/roles.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.