> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> Create and manage users, roles, and project access.

Use the Users API to manage people in your workspace. You can create users linked to existing accounts, update profiles and roles, and inspect related projects or artifacts.

## Basic request and response

Use `GET /api/v1/app/me` to verify your token and user context.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/me" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "id": "user_4b7c2a1d9e5f3c8b",
    "org_id": "org_2f3a9d1c7b5e4a8f",
    "account_id": "acct_6c8a1f3b2d4e5f7a",
    "name": "Sasha Patel",
    "email": "sasha@auroralabs.com",
    "job_position_name": "Product Ops Lead",
    "job_position_description": "Owns release coordination and analytics.",
    "state": "Active",
    "roles": ["AppAdmin"],
    "created_at": "2026-02-08T14:12:45Z"
  }
  ```
</Accordion>

## List users

<Accordion title="Endpoint parameters">
  | Type  | Name          | Required | Notes                                      |
  | ----- | ------------- | -------- | ------------------------------------------ |
  | Query | `page`        | No       | Absolute page number to fetch, 1-based.    |
  | Query | `page_size`   | No       | Number of items per page.                  |
  | Query | `page_order`  | No       | `ASC` or `DESC`.                           |
  | Query | `after`       | No       | Cursor or value to paginate after.         |
  | Query | `before`      | No       | Cursor or value to paginate before.        |
  | Query | `first`       | No       | Limit to the first N items after a cursor. |
  | Query | `last`        | No       | Limit to the last N items before a cursor. |
  | Query | `total_count` | No       | Include total count in the response.       |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user?page=1&page_size=20" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "data": [
      {
        "id": "user_4b7c2a1d9e5f3c8b",
        "org_id": "org_2f3a9d1c7b5e4a8f",
        "account_id": "acct_6c8a1f3b2d4e5f7a",
        "name": "Sasha Patel",
        "email": "sasha@auroralabs.com",
        "state": "Active",
        "roles": ["AppAdmin"],
        "created_at": "2026-02-08T14:12:45Z"
      }
    ],
    "has_next_page": false,
    "has_previous_page": false,
    "total_count": 1
  }
  ```
</Accordion>

## Create a user

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/user" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "{accountID}",
    "role": "AppMember",
    "user_info": {
      "email": "sasha@auroralabs.com",
      "name": "Sasha Patel",
      "given_name": "Sasha",
      "family_name": "Patel"
    }
  }'
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "id": "user_4b7c2a1d9e5f3c8b",
    "org_id": "org_2f3a9d1c7b5e4a8f",
    "account_id": "acct_6c8a1f3b2d4e5f7a",
    "name": "Sasha Patel",
    "email": "sasha@auroralabs.com",
    "state": "Active",
    "roles": ["AppMember"],
    "created_at": "2026-02-08T14:12:45Z"
  }
  ```
</Accordion>

## Get or update a user

<Tabs>
  <Tab title="Get user">
    ```bash theme={null}
    curl "https://{BASE_URL}/api/v1/app/user/{userID}" \
      -H "Authorization: Bearer {API_TOKEN}"
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "user_4b7c2a1d9e5f3c8b",
        "org_id": "org_2f3a9d1c7b5e4a8f",
        "account_id": "acct_6c8a1f3b2d4e5f7a",
        "name": "Sasha Patel",
        "email": "sasha@auroralabs.com",
        "state": "Active",
        "roles": ["AppMember"],
        "created_at": "2026-02-08T14:12:45Z"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Update user">
    <Accordion title="Endpoint parameters">
      | Type | Name     | Required | Notes                     |
      | ---- | -------- | -------- | ------------------------- |
      | Path | `userID` | Yes      | User identifier.          |
      | Body | `name`   | No       | User display name.        |
      | Body | `role`   | No       | Workspace role to assign. |
    </Accordion>

    ```bash theme={null}
    curl -X PUT "https://{BASE_URL}/api/v1/app/user/{userID}" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Sasha Patel",
        "role": "AppAdmin"
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "user_4b7c2a1d9e5f3c8b",
        "org_id": "org_2f3a9d1c7b5e4a8f",
        "account_id": "acct_6c8a1f3b2d4e5f7a",
        "name": "Sasha Patel",
        "email": "sasha@auroralabs.com",
        "state": "Active",
        "roles": ["AppAdmin"],
        "created_at": "2026-02-08T14:12:45Z"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## Activate or deactivate a user

<Tabs>
  <Tab title="Deactivate">
    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/user/{userID}/deactivate" \
      -H "Authorization: Bearer {API_TOKEN}"
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "user_9d1c3b5a7f2e4c6d",
        "state": "Inactive"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Activate">
    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/user/{userID}/activate" \
      -H "Authorization: Bearer {API_TOKEN}"
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "user_9d1c3b5a7f2e4c6d",
        "state": "Active"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## List projects for a user

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user/{userID}/project" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "data": [
      {
        "id": "proj_7a5c3e1b9d2f4a6c",
        "name": "Customer Insights",
        "goal": "Summarize weekly support trends.",
        "deadline": "2026-03-01T00:00:00Z",
        "visibility": "Private",
        "member_count": 4,
        "default_member_role": "Editor",
        "default_role_enabled": true,
        "project_context": "Support analytics for Q1.",
        "answer_context": "Use approved templates.",
        "is_pinned": true
      }
    ],
    "has_next_page": false,
    "has_previous_page": false,
    "total_count": 1
  }
  ```
</Accordion>

## Latest artifacts for a user

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user/{userID}/latest-artifacts" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "id": "artifact_2b4d6f8a1c3e5a7b",
      "project_id": "proj_7a5c3e1b9d2f4a6c",
      "name": "Q1 Support Summary",
      "type": "Document",
      "source": "User",
      "state": "Published",
      "ingest_status": "Done",
      "has_content": true,
      "created_at": "2026-02-08T14:30:12Z"
    }
  ]
  ```
</Accordion>

## User integrations

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user/integrations" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "id": "conf_8a7b6c5d4e3f2a1b",
      "user_id": "user_4b7c2a1d9e5f3c8b",
      "org_id": "org_2f3a9d1c7b5e4a8f",
      "type": "Confluence",
      "created_at": "2026-02-05T09:10:00Z",
      "updated_at": "2026-02-08T10:02:11Z"
    }
  ]
  ```
</Accordion>

## Errors and edge cases

* **409**: duplicate user email or account linkage.
* **400**: invalid role.
* **404**: user not found.