> ## 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.

# Organization API

> Org units, leads, members, org-scoped user reads, the access overview, and the identity provider card: the organization and SSO features.

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

On Individual, reads stay open, but writes to org units, org users, and directory sync return `402` with code `plan_feature_not_included`. On a self-hosted open-source server, these routes aren't served.

These routes back **Access control** in the dashboard. Behavioral guide: [User and org management](https://docs.nasiko.com/governance/access-control/users-and-teams.md).

| Method | Path | Who |
| - | - | - |
| `GET` | `/api/org/context` | Any signed-in user (themselves) |
| `GET` | `/api/org/users` | `manager` or above |
| `PUT` | `/api/org/users/{id}/role` | `manager` or above, within rank |
| `PUT` | `/api/org/users/{id}/placement` | `manager` or above, within their units |
| `GET` | `/api/org/units` | `manager` or above |
| `POST` | `/api/org/units` | `admin` for a top-level unit; a unit's lead beneath it |
| `DELETE` | `/api/org/units/{id}` | `admin` |
| `PUT` | `/api/org/units/{id}/lead` | `admin`, or a lead of the unit or a unit above it |
| `GET` `POST` | `/api/org/units/{id}/members` | `admin`, or a lead of the unit or a unit above it |
| `DELETE` | `/api/org/units/{id}/members/{user_id}` | `admin`, or a lead of the unit or a unit above it |
| `GET` | `/api/access-control/overview` | `admin` |
| `GET` | `/api/identity/provider` | `admin` |
| `POST` | `/api/identity/provider/reset-org-data` | `admin` |

A superuser passes every check. Send the session token as `Authorization: Bearer <token>`. A missing or invalid token returns `401`:

```json theme={null}
{ "data": null, "status_code": 401, "message": "missing or invalid token" }
```

**Below the role floor, reads don't fail.** A caller below `manager` gets `200` with `{"available": false}` from `GET /api/org/users` and `GET /api/org/units`, and a non-admin gets the same from `GET /api/access-control/overview`. Treat it as "not available to you".

**Out-of-scope units and users return `404`, not `403`,** so a manager can't probe the parts of the org they don't lead.

## Response envelope (org units)

The `/api/org/units` routes wrap every response, success or error, in one envelope:

```json theme={null}
{ "data": ..., "status_code": 200, "message": "3 org units fetched successfully" }
```

Errors carry `"data": null`, the HTTP status, and a message. Successful writes with nothing to return answer `200` with `"data": null`.

## Org context

`GET /api/org/context`

Who you are in the org structure. Any signed-in user, about themselves.

```json theme={null}
{
  "id": "5b1e2c4a-...",
  "role": "manager",
  "unit_ids": ["9a1c..."],
  "unit_names": ["Platform"],
  "leads": ["9a1c..."],
  "is_superuser": false,
  "awaiting_assignment": false
}
```

| Field | Type | Description |
| - | - | - |
| `role` | string | `admin`, `manager`, or `member` |
| `unit_ids`, `unit_names` | array | Units you're placed in directly. Units above them aren't listed |
| `leads` | UUID\[] | Units you lead. This, not `role`, is the extent of what a manager administers |
| `awaiting_assignment` | boolean | `true` for a `member` who isn't placed anywhere |

## Users in your scope

### List users

`GET /api/org/users`

Users the caller can see: everyone for an `admin`; for a `manager`, people in their units and everyone beneath the units they lead.

| Query | Type | Default | Description |
| - | - | - | - |
| `q` | string | — | Matches username, email, or display name (case-insensitive substring) |
| `limit` | integer | `20` | Page size |
| `offset` | integer | `0` | Rows to skip |

```bash theme={null}
curl "https://<your-host>/api/org/users?q=ali&limit=20" \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "data": [
    {
      "id": "5b1e2c4a-...",
      "username": "alice",
      "email": "alice@acme.com",
      "display_name": "Alice Ng",
      "role": "member",
      "unit_ids": ["9a1c..."],
      "unit_names": ["Platform"],
      "is_active": true
    }
  ],
  "total": 1
}
```

Sorted by username. `total` counts every match, not just this page.

### Change a role

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

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

```bash theme={null}
curl -X PUT https://<your-host>/api/org/users/5b1e2c4a-.../role \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "member"}'
```

A `manager` can act only on users in their scope whose current role is below `manager`, and can grant only `member`. An `admin` and a superuser aren't limited by rank. Nobody can change their own role, and the last admin can't be demoted. The user is signed out of every session. Demoting to `member` also clears them as lead of any unit.

| Status | Meaning |
| - | - |
| `204` | Changed |
| `400` | `{"error": "invalid role; valid: admin, manager, member"}` |
| `403` | Below `manager`, the rank rule, or your own role |
| `404` | No such user, or outside your scope |
| `409` | Would demote the last admin |

### Set manual placement

`PUT /api/org/users/{id}/placement`

Replaces the units a user is placed in by hand. Directory-synced placements are left as they are.

| Body field | Type | Required | Description |
| - | - | - | - |
| `unit_ids` | UUID\[] | No | The full set of units to place the user in. `[]` (or omitting it) clears their manual placement |

A `manager` can place only users they can see, and only into units they lead or that sit beneath one they lead. The role doesn't change.

| Status | Meaning |
| - | - |
| `204` | Updated |
| `400` | `{"error": "unknown org unit(s): <ids>"}` |
| `403` | `{"error": "org unit <id> is outside the subtree you lead"}` |
| `404` | No such user, or outside your scope |

## Org units

### List units

`GET /api/org/units`

| Query | Type | Default | Description |
| - | - | - | - |
| `tree` | boolean | `false` | Return nested units with `children` instead of a flat list |
| `parent_id` | UUID | — | Only the direct children of this unit |
| `q` | string | — | Case-insensitive name search |

An `admin` sees every unit. A `manager` sees the units they lead and everything beneath them; with `tree=true` a led unit whose parent they can't see becomes a top-level node.

```bash theme={null}
curl "https://<your-host>/api/org/units?tree=true" -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "data": [
    {
      "id": "1f0e...",
      "parent_id": null,
      "name": "Engineering",
      "depth": 1,
      "lead_id": "7d2a...",
      "lead_username": "dana",
      "source": "idp",
      "provider": "entra",
      "external_id": "c0a8...",
      "idp_synced_at": "2026-11-14T05:00:00Z",
      "member_count": 4,
      "created_at": "2026-10-01T12:00:00Z",
      "children": [
        { "id": "9a1c...", "parent_id": "1f0e...", "name": "Platform", "depth": 2, "source": "manual", "member_count": 6, "children": [] }
      ]
    }
  ],
  "status_code": 200,
  "message": "2 org units fetched successfully"
}
```

| Field | Type | Description |
| - | - | - |
| `depth` | integer | `1` for a top-level unit |
| `lead_id`, `lead_username` | UUID / string \| null | The unit's lead |
| `source` | string | `idp` for a unit from your identity provider, which the next sync can change; `manual` for one created in Nasiko |
| `provider`, `external_id`, `idp_synced_at` | string \| null | Identity-provider details for an `idp` unit |
| `member_count` | integer | Direct members only |

### Create a unit

`POST /api/org/units`

| Body field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Unit name. Must be unique among its siblings |
| `parent_id` | UUID | No | Parent unit. Omit for a top-level unit, which needs `admin` |
| `settings` | object | No | Free-form JSON stored with the unit. Default `{}` |

```bash theme={null}
curl -X POST https://<your-host>/api/org/units \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "SRE", "parent_id": "1f0e..."}'
```

`201`:

```json theme={null}
{ "data": { "id": "4b7d..." }, "status_code": 201, "message": "org unit created successfully" }
```

| Status | Meaning |
| - | - |
| `400` | `name is required` |
| `403` | A top-level unit without `admin`: `requires an admin` |
| `404` | Parent outside your scope: `no such org unit` |
| `409` | `duplicate_name: a sibling unit already has that name` |

Units created here are always `manual`.

### Delete a unit

`DELETE /api/org/units/{id}`

| Query | Type | Default | Description |
| - | - | - | - |
| `cascade` | boolean | `false` | Also delete every unit beneath it |

Without `cascade`, a unit with child units is refused with `409`: `unit_has_children: <n> live child unit(s); pass ?cascade=true to delete the subtree`. Grants on a deleted unit stop reaching anyone. Requires `admin` (`403`: `requires an admin`). `200` with `org unit deleted successfully`, or `404`.

### Appoint or clear a lead

`PUT /api/org/units/{id}/lead`

| Body field | Type | Required | Description |
| - | - | - | - |
| `lead_id` | UUID \| null | No | The new lead. `null` or omitted clears the lead |

Appointing a `member` makes them a `manager`. An `admin` keeps their role. The previous lead returns to `member` if they no longer lead any unit. `200` with `unit lead updated successfully`. `400` with `no such user`. `404` if the unit is outside your scope.

### Members

`GET /api/org/units/{id}/members`

| Query | Type | Default | Description |
| - | - | - | - |
| `include_descendants` | boolean | `false` | Include members of every unit beneath |

```json theme={null}
{
  "data": [
    {
      "id": "5b1e2c4a-...",
      "username": "alice",
      "email": "alice@acme.com",
      "display_name": "Alice Ng",
      "role": "member",
      "source": "manual",
      "unit_id": "9a1c...",
      "unit_name": "Platform"
    }
  ],
  "status_code": 200,
  "message": "1 member fetched successfully"
}
```

`source` is `idp` for a directory-synced membership and `manual` for one added in Nasiko. `unit_id` is the unit the person actually sits in, which differs from the requested unit with `include_descendants`.

`POST /api/org/units/{id}/members`

| Body field | Type | Required | Description |
| - | - | - | - |
| `user_ids` | UUID\[] | Yes | Users to add. Adding someone already in the unit is a no-op |

`200` with `<n> member(s) added successfully`. `400` with `one or more users do not exist`.

`DELETE /api/org/units/{id}/members/{user_id}`

`200` with `member removed successfully`. `404` with `not a member of this unit`. `409` when the membership came from your identity provider. Remove the person from the group there instead.

## Access overview

`GET /api/access-control/overview`

The admin summary at the top of **Access control → Org structure**. `admin` or superuser; anyone else gets `{"available": false}`.

```json theme={null}
{
  "stats": { "admins": 2, "root_units": 3, "units": 11, "users": 48, "agents": 17 },
  "warnings": [
    { "type": "warning", "count": 5, "label": "Users not placed in any org unit" },
    { "type": "error", "count": 1, "label": "Top-level units without a lead" },
    { "type": "info", "count": 2, "label": "Units with no direct members" }
  ],
  "units": [
    { "name": "Engineering", "lead": "Dana Lee", "descendants_count": 4, "members_count": 31, "agents_count": 9 }
  ],
  "unassigned_users": [
    { "id": "...", "username": "sam", "display_name": null, "email": "sam@acme.com", "role": "member", "created_at": "2026-11-13T10:00:00Z" }
  ]
}
```

`units` lists top-level units with counts for their whole subtree. `unassigned_users` lists up to 50 unplaced users, newest first.

## Identity provider

### Provider card

`GET /api/identity/provider`

```json theme={null}
{
  "configured": true,
  "provider": "entra",
  "kind": "entra",
  "mode": "full",
  "directory_enabled": true,
  "last_synced_at": "2026-11-14T05:00:00Z",
  "required_permissions": ["Group.Read.All", "GroupMember.Read.All", "User.Read.All"]
}
```

| Field | Type | Description |
| - | - | - |
| `mode` | string | `full` when directory groups are available, `flat` when only sign-in is |
| `directory_enabled` | boolean | Whether Nasiko reads your directory |
| `last_synced_at` | timestamp \| null | Last directory sync |
| `required_permissions` | string\[] | What the directory connection needs from your provider |

`404` with `{"error": "identity is not configured"}` when SSO isn't set up. `403` with `{"error": "requires an admin"}` below `admin`.

### Reset organization data

`POST /api/identity/provider/reset-org-data`

Removes every directory-synced unit and membership for the active provider and resets the affected users, other than admins and superusers, to `member`. Manual units and memberships stay. SSO sign-in keeps working. The next directory sync or SCIM push recreates the structure.

```json theme={null}
{
  "status": "reset_complete",
  "units_deleted": 9,
  "memberships_removed": 41,
  "roles_reset": 3,
  "users_affected": 38
}
```


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