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

# Users API (organization)

> How the users routes behave with the organization and SSO features: org-scoped reads, unit placement, roles, and session revocation.

> [!NOTE]
>
> **Plans:** Pro and Enterprise. **Self-hosted:** Enterprise license.

This page covers the users routes as Nasiko Cloud and self-hosted Enterprise servers serve them. The paths are the same as on a self-hosted open-source server, but reads are scoped to the org structure and user records carry unit placement. On Individual, reads stay open, but creating, changing, and deleting users and changing roles return `402` with code `plan_feature_not_included`.

| Method | Path | Who | Organization behavior |
| - | - | - | - |
| `GET` | `/api/users` | `manager` or above | Scoped to the caller's units. Extra filters `role`, `unit`, `status` |
| `GET` | `/api/users/stats` | `manager` or above | Counts within the caller's scope |
| `GET` | `/api/users/me` | Any signed-in user | Includes unit placement and sign-in method |
| `GET` | `/api/users/{id}` | `admin` or superuser | Includes unit placement |
| `GET` | `/api/users/me/accessible-agents` | Any signed-in user | Includes agents reached through org unit grants |
| `GET` | `/api/users/{id}/accessible-agents` | Yourself, or a user in your scope | Same, for another user |
| `PUT` | `/api/users/{id}` | `admin` or superuser | Also sets manual unit placement |
| `PUT` | `/api/users/{id}/role` | `admin` or superuser | Roles are `admin`, `manager`, `member`. Signs the user out |
| `POST` | `/api/auth/tokens/revoke-user/{id}` | Superuser | Sign one user out of every session |
| `POST` | `/api/auth/tokens/revoke-all` | Superuser | Sign every user out |

Creating, deleting, deactivating, and reinstating users, and issuing new credentials, work as on a self-hosted open-source server. Callers below the "Who" floor on the reads get `200` with `{"available": false}` rather than an error.

## The user record

`GET /api/users/me`, `GET /api/users/{id}`, the items of `GET /api/users`, and the response of `PUT /api/users/{id}` share one shape:

```json theme={null}
{
  "id": "5b1e2c4a-...",
  "username": "alice",
  "email": "alice@acme.com",
  "display_name": "Alice Ng",
  "is_superuser": false,
  "is_active": true,
  "role": "member",
  "auth_provider": "oidc",
  "unit_ids": ["9a1c..."],
  "unit_names": ["Platform"],
  "created_at": "2026-10-02T08:00:00Z",
  "last_login": "2026-11-14T07:31:00Z"
}
```

| Field | Type | Description |
| - | - | - |
| `role` | string | `admin`, `manager`, or `member` |
| `auth_provider` | string \| null | `oidc` for users who sign in through SSO. They have no Nasiko password to change |
| `unit_ids`, `unit_names` | array | Units the user is placed in directly, sorted by name |

## List users

`GET /api/users`

| Query | Type | Default | Description |
| - | - | - | - |
| `q` | string | — | Substring of username, email, or display name |
| `role` | string | — | `admin`, `manager`, or `member` |
| `unit` | UUID | — | Users in this unit or any unit beneath it |
| `status` | string | — | `active` or `disabled` |
| `limit` | integer | `20` | Page size |
| `offset` | integer | `0` | Rows to skip |

An `admin` sees everyone. A `manager` sees people in their units and everyone beneath the units they lead, whatever filters they send. Newest first.

```bash theme={null}
curl "https://<your-host>/api/users?role=member&status=active&limit=50" \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{ "data": [ { "id": "5b1e2c4a-...", "username": "alice", "role": "member", "unit_names": ["Platform"], "...": "..." } ], "total": 1 }
```

`400` with `{"error": "invalid role; valid: admin, manager, member"}` or `{"error": "invalid status; valid: active, disabled"}`.

`GET /api/users/stats` returns `{"available": true, "total": 48, "admins": 2}`, counted over the same scope. `admins` includes superusers.

## Agents a user can reach

`GET /api/users/me/accessible-agents` and `GET /api/users/{id}/accessible-agents`

Agents the user owns, public agents, and agents shared with them directly or through an org unit they belong to.

```json theme={null}
{
  "data": {
    "accessible_agents": [
      { "id": "a1b2...", "name": "research", "description": "Finds sources", "status": "running", "owner_id": "5b1e...", "is_public": false }
    ],
    "owned": [ { "id": "a1b2...", "name": "research", "...": "..." } ],
    "shared": [],
    "grant_list": []
  }
}
```

`owned` and `shared` split `accessible_agents` by owner. `grant_list` is always empty. For another user outside your scope: `403` with `{"error": "you do not have permission to view this user's agents"}`.

## Update a user

`PUT /api/users/{id}`

| Body field | Type | Required | Description |
| - | - | - | - |
| `username` | string | No | New username |
| `email` | string | No | New email |
| `display_name` | string | No | Display name |
| `password` | string | No | New password |
| `is_active` | boolean | No | `false` deactivates the user |
| `unit_ids` | UUID\[] | No | Replace the user's manual unit placement. `[]` clears it. Omit to leave it alone. Directory-synced placements aren't changed |

Fields you leave out are unchanged. Returns `200` with the updated user record.

| Status | Meaning |
| - | - |
| `400` | Empty username or email, password too short, or `{"error": "org unit not found"}` |
| `403` | Deactivating your own account |
| `404` | No such user |
| `409` | Username or email taken, or deactivating the last admin |

## Change a role

`PUT /api/users/{id}/role`

| Body field | Type | Required | Description |
| - | - | - | - |
| `role` | string | Yes | `admin`, `manager`, or `member` |

`204` on success. The user is signed out of every session. Demoting to `member` also clears them as lead of any unit. `400` for an unknown role, `403` for your own role or, unless you're a superuser, a superuser's role, `404` for no such user, `409` for demoting the last admin. Managers change roles through [`PUT /api/org/users/{id}/role`](https://docs.nasiko.com/api-reference/enterprise/organization#change-a-role) instead.

## Revoke sessions

`POST /api/auth/tokens/revoke-user/{id}` signs one user out everywhere. `POST /api/auth/tokens/revoke-all` signs out every user, including you. Both need a superuser, take no body, and return:

```json theme={null}
{ "revoked": 3 }
```

`revoked` is the number of sessions ended. CLI: `nasiko-ee admin user-revoke <user-id>` and `nasiko-ee admin revoke-all`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.