> 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/business-data-repository/api-reference/actors/users.md).
# Users
Reference for user accounts and user-defined catalog items: the read-only User object and the mutations that manage hierarchical catalog entries.
{% hint style="warning" %}
**Navixy GraphQL API is a work in progress.** This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.
{% endhint %}
User accounts representing human operators who access the system through the UI or API.
## Mutations
### userCatalogItemCreate
Creates a new user catalog item.
```graphql
userCatalogItemCreate(
input: UserCatalogItemCreateInput!
): UserCatalogItemPayload
```
**Arguments**
| Name | Type | Description |
| ------- | ----------------------------- | --------------------------------------- |
| `input` | `UserCatalogItemCreateInput!` | The input fields for creating the item. |
**Input types:**
UserCatalogItemCreateInput
Input for creating a user catalog item.
| Field | Type | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `workspaceId` | `ID!` | The workspace that will own the item. |
| `catalogId` | `ID!` | The catalog to add the item to. |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | The machine-readable code, unique within the catalog and workspace. Auto-generated from title if omitted. |
| `title` | `String!` | The display name. |
| `order` | `Int` | The display order. Auto-calculated as last position if omitted. |
| `parentId` | `ID` | The parent item ID for hierarchical catalogs. |
| `meta` | [CatalogItemMetaInput](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmetainput) | The display properties. |
CatalogItemMetaInput
Display properties for catalog items.
| Field | Type | Description |
| ------------- | --------- | ------------------------------------------------- |
| `description` | `String` | The description. |
| `hidden` | `Boolean` | Whether the item is hidden from regular UI lists. |
**Output types:**
UserCatalogItemPayload
The result of a user catalog item mutation.
| Field | Type | Description |
| ------ | ------------------------------------ | ----------------------------------------- |
| `item` | [UserCatalogItem](#usercatalogitem)! | The created or updated user catalog item. |
UserCatalogItem (entity)
A user-defined catalog item that supports hierarchical workspace.
**Implements:** [CatalogItem](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitem), [HierarchicalCatalogItem](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#hierarchicalcatalogitem), [Node](/docs/navixy-graphql-api/core-api-reference/common.md#node), [Versioned](/docs/navixy-graphql-api/core-api-reference/common.md#versioned), [Titled](/docs/navixy-graphql-api/core-api-reference/common.md#titled)
| Field | Type | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `id` | `ID!` | A globally unique identifier. |
| `version` | `Int!` | The version number for optimistic locking. |
| `title` | `String!` | The human-readable display name. Can be localized. |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | A machine-readable code, unique within the catalog scope. |
| `order` | `Int!` | The display order within the same level or category. |
| `catalog` | [Catalog](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalog)! | The catalog this item belongs to. |
| `workspace` | [Workspace](/docs/navixy-graphql-api/business-data-repository/api-reference/workspaces.md#workspace) | The workspace that owns this item. Null for system items. |
| `meta` | [CatalogItemMeta](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmeta)! | Metadata about this item including description, origin, and display properties. |
| `parent` | [UserCatalogItem](#usercatalogitem) | The parent item in the hierarchy. Null for root items. |
| `children` | [UserCatalogItemConnection](#usercatalogitemconnection)! | The child items in the hierarchy. |
***
### userCatalogItemUpdate
Updates a user catalog item.
```graphql
userCatalogItemUpdate(
input: UserCatalogItemUpdateInput!
): UserCatalogItemPayload
```
**Arguments**
| Name | Type | Description |
| ------- | ----------------------------- | --------------------------------------- |
| `input` | `UserCatalogItemUpdateInput!` | The input fields for updating the item. |
**Input types:**
UserCatalogItemUpdateInput
Input for updating a user catalog item.
| Field | Type | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The item ID to update. |
| `version` | `Int` | The current version for optimistic locking. If omitted, auto-increments without conflict check. |
| `title` | `String` | The new display name. |
| `order` | `Int` | The new display order. |
| `parentId` | `ID` | The new parent ID for hierarchical items. |
| `meta` | [CatalogItemMetaInput](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmetainput) | The display properties. |
CatalogItemMetaInput
Display properties for catalog items.
| Field | Type | Description |
| ------------- | --------- | ------------------------------------------------- |
| `description` | `String` | The description. |
| `hidden` | `Boolean` | Whether the item is hidden from regular UI lists. |
**Output types:**
UserCatalogItemPayload
The result of a user catalog item mutation.
| Field | Type | Description |
| ------ | ------------------------------------ | ----------------------------------------- |
| `item` | [UserCatalogItem](#usercatalogitem)! | The created or updated user catalog item. |
UserCatalogItem (entity)
A user-defined catalog item that supports hierarchical workspace.
**Implements:** [CatalogItem](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitem), [HierarchicalCatalogItem](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#hierarchicalcatalogitem), [Node](/docs/navixy-graphql-api/core-api-reference/common.md#node), [Versioned](/docs/navixy-graphql-api/core-api-reference/common.md#versioned), [Titled](/docs/navixy-graphql-api/core-api-reference/common.md#titled)
| Field | Type | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `id` | `ID!` | A globally unique identifier. |
| `version` | `Int!` | The version number for optimistic locking. |
| `title` | `String!` | The human-readable display name. Can be localized. |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | A machine-readable code, unique within the catalog scope. |
| `order` | `Int!` | The display order within the same level or category. |
| `catalog` | [Catalog](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalog)! | The catalog this item belongs to. |
| `workspace` | [Workspace](/docs/navixy-graphql-api/business-data-repository/api-reference/workspaces.md#workspace) | The workspace that owns this item. Null for system items. |
| `meta` | [CatalogItemMeta](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmeta)! | Metadata about this item including description, origin, and display properties. |
| `parent` | [UserCatalogItem](#usercatalogitem) | The parent item in the hierarchy. Null for root items. |
| `children` | [UserCatalogItemConnection](#usercatalogitemconnection)! | The child items in the hierarchy. |
***
### userCatalogItemDelete
Deletes a user catalog item.
```graphql
userCatalogItemDelete(
input: CatalogItemDeleteInput!
): DeletePayload
```
**Arguments**
| Name | Type | Description |
| ------- | ------------------------- | --------------------------------------- |
| `input` | `CatalogItemDeleteInput!` | The input fields for deleting the item. |
**Input types:**
CatalogItemDeleteInput
Input for deleting a catalog item.
| Field | Type | Description |
| --------- | ----- | ----------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The catalog item ID to delete. |
| `version` | `Int` | The current version for optimistic locking. If omitted, auto-increments without conflict check. |
**Output types:**
DeletePayload
The result of a delete mutation.
| Field | Type | Description |
| ----------- | ----- | ----------------------------- |
| `deletedId` | `ID!` | The ID of the deleted entity. |
***
## Objects
### UserCatalogItem
A user-defined catalog item that supports hierarchical workspace.
**Implements:** [CatalogItem](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitem), [HierarchicalCatalogItem](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#hierarchicalcatalogitem), [Node](/docs/navixy-graphql-api/core-api-reference/common.md#node), [Versioned](/docs/navixy-graphql-api/core-api-reference/common.md#versioned), [Titled](/docs/navixy-graphql-api/core-api-reference/common.md#titled)
| Field | Type | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `id` | `ID!` | A globally unique identifier. |
| `version` | `Int!` | The version number for optimistic locking. |
| `title` | `String!` | The human-readable display name. Can be localized. |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code)! | A machine-readable code, unique within the catalog scope. |
| `order` | `Int!` | The display order within the same level or category. |
| `catalog` | [Catalog](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalog)! | The catalog this item belongs to. |
| `workspace` | [Workspace](/docs/navixy-graphql-api/business-data-repository/api-reference/workspaces.md#workspace) | The workspace that owns this item. Null for system items. |
| `meta` | [CatalogItemMeta](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmeta)! | Metadata about this item including description, origin, and display properties. |
| `parent` | [UserCatalogItem](#usercatalogitem) | The parent item in the hierarchy. Null for root items. |
| `children` | [UserCatalogItemConnection](#usercatalogitemconnection)! | The child items in the hierarchy. |
***
### User
A human user account authenticated via an identity provider.
**Implements:** [Actor](/docs/navixy-graphql-api/business-data-repository/api-reference/actors.md#actor), [Node](/docs/navixy-graphql-api/core-api-reference/common.md#node), [Versioned](/docs/navixy-graphql-api/core-api-reference/common.md#versioned), [Titled](/docs/navixy-graphql-api/core-api-reference/common.md#titled)
| Field | Type | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `ID!` | A globally unique identifier. |
| `version` | `Int!` | The version number for optimistic locking. Incremented on each update. Can be provided in update/delete mutations to prevent lost updates. If omitted, the update proceeds without stale-read protection. |
| `title` | `String!` | The display name for the user. This is the user's full name for display purposes. |
| `name` | [PersonName](/docs/navixy-graphql-api/business-data-repository/api-reference/actors.md#personname)! | The structured name components from the identity provider. |
| `identityProvider` | `String!` | The identity provider name (keycloak, auth0, okta, etc.). |
| `identityProviderId` | `String!` | The user's unique ID in the identity provider. |
| `email` | [EmailAddress](/docs/navixy-graphql-api/core-api-reference/common.md#emailaddress)! | The user's primary email address. |
| `externalId` | `String` | An external system identifier for integration purposes. |
| `isActive` | `Boolean!` | Whether this user account is active. |
| `memberships` | [MemberConnection](/docs/navixy-graphql-api/business-data-repository/api-reference/workspaces/members.md#memberconnection)! | The workspace memberships for this user. |
***
### UserCatalogItemPayload
The result of a user catalog item mutation.
| Field | Type | Description |
| ------ | ------------------------------------ | ----------------------------------------- |
| `item` | [UserCatalogItem](#usercatalogitem)! | The created or updated user catalog item. |
***
## Inputs
### UserCatalogItemCreateInput
Input for creating a user catalog item.
| Field | Type | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `workspaceId` | `ID!` | The workspace that will own the item. |
| `catalogId` | `ID!` | The catalog to add the item to. |
| `code` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#code) | The machine-readable code, unique within the catalog and workspace. Auto-generated from title if omitted. |
| `title` | `String!` | The display name. |
| `order` | `Int` | The display order. Auto-calculated as last position if omitted. |
| `parentId` | `ID` | The parent item ID for hierarchical catalogs. |
| `meta` | [CatalogItemMetaInput](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmetainput) | The display properties. |
***
### UserCatalogItemUpdateInput
Input for updating a user catalog item.
| Field | Type | Description |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `id` | `ID!` | The item ID to update. |
| `version` | `Int` | The current version for optimistic locking. If omitted, auto-increments without conflict check. |
| `title` | `String` | The new display name. |
| `order` | `Int` | The new display order. |
| `parentId` | `ID` | The new parent ID for hierarchical items. |
| `meta` | [CatalogItemMetaInput](/docs/navixy-graphql-api/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmetainput) | The display properties. |
***
## Pagination types
### UserCatalogItemConnection
A paginated list of UserCatalogItem items.
**Implements:** [Connection](/docs/navixy-graphql-api/core-api-reference/common.md#connection)
| Field | Type | Description |
| ---------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `edges` | \[[UserCatalogItemEdge](#usercatalogitemedge)!]! | A list of edges. |
| `nodes` | \[[UserCatalogItem](#usercatalogitem)!]! | A list of nodes in the connection (without edge metadata). |
| `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 total count of items matching the filter. |
***
### UserCatalogItemEdge
An edge in the UserCatalogItem connection.
**Implements:** [Edge](/docs/navixy-graphql-api/core-api-reference/common.md#edge)
| Field | Type | Description |
| -------- | ------------------------------------ | --------------------------------------------- |
| `cursor` | `String!` | An opaque cursor for this edge. |
| `node` | [UserCatalogItem](#usercatalogitem)! | The user catalog item at the end of the edge. |
***
### UserConnection
A paginated list of User items.
**Implements:** [Connection](/docs/navixy-graphql-api/core-api-reference/common.md#connection)
| Field | Type | Description |
| ---------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `edges` | \[[UserEdge](#useredge)!]! | A list of edges. |
| `nodes` | \[[User](#user)!]! | A list of nodes in the connection (without edge metadata). |
| `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 total count of items matching the filter. |
***
### UserEdge
An edge in the User connection.
**Implements:** [Edge](/docs/navixy-graphql-api/core-api-reference/common.md#edge)
| Field | Type | Description |
| -------- | -------------- | -------------------------------- |
| `cursor` | `String!` | An opaque cursor for this edge. |
| `node` | [User](#user)! | The user at the end of the edge. |
***
## See also
* [Pagination](/docs/navixy-graphql-api/pagination.md)
* [Filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting.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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://navixy.com/docs/navixy-graphql-api/business-data-repository/api-reference/actors/users.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.