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

# SCIM API

> SCIM 2.0 provisioning endpoints and SCIM token management, part of the organization and SSO features.

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

SCIM is part of the organization and SSO features and needs SSO configured. On Individual, SCIM writes return `402` with code `plan_feature_not_included`; reads stay open.

Your identity provider calls the SCIM endpoints. You manage the tokens it uses in **Settings → Security → Single sign-on**, under **SCIM provisioning**, or with the token routes below. Setup guide: [SCIM provisioning](https://docs.nasiko.com/governance/sso-and-scim.md#scim-provisioning).

| Method | Path | Who |
| - | - | - |
| `GET` | `/api/settings/scim/tokens` | `admin` role or superuser |
| `POST` | `/api/settings/scim/tokens` | `admin` role or superuser |
| `DELETE` | `/api/settings/scim/tokens/{id}` | `admin` role or superuser |
| `GET` | `/scim/v2/ServiceProviderConfig` | SCIM token |
| `GET` | `/scim/v2/Schemas` | SCIM token |
| `GET` | `/scim/v2/ResourceTypes` | SCIM token |
| `GET` `POST` | `/scim/v2/Users` | SCIM token |
| `GET` `PUT` `PATCH` `DELETE` | `/scim/v2/Users/{id}` | SCIM token |
| `GET` `POST` | `/scim/v2/Groups` | SCIM token |
| `GET` `PUT` `PATCH` `DELETE` | `/scim/v2/Groups/{id}` | SCIM token |

## SCIM tokens

The token routes take a dashboard session (`Authorization: Bearer <session-token>`) from a user with the `admin` role or a superuser. Anyone else gets `403`.

### List tokens

`GET /api/settings/scim/tokens`

Returns every token, newest first, including revoked ones. The token value is never returned.

```json theme={null}
{
  "tokens": [
    {
      "id": "3f6c1e0a-...",
      "provider": "entra",
      "description": "Generated from settings page",
      "created_at": "2026-11-02T09:14:00Z",
      "expires_at": null,
      "revoked_at": null,
      "last_used_at": "2026-11-14T06:02:11Z"
    }
  ]
}
```

### Generate a token

`POST /api/settings/scim/tokens`

| Body field | Type | Required | Description |
| - | - | - | - |
| `provider` | string | No | The identity provider this token is for. Use your configured provider kind, for example `entra` or `okta`. Default `default`. A token whose provider doesn't match the server's active identity provider is refused on every SCIM call |
| `description` | string | No | Free-text label shown in the token list |
| `expires_at` | timestamp | No | RFC 3339. Omit for a token that doesn't expire |

```bash theme={null}
curl -X POST https://<your-host>/api/settings/scim/tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"provider": "entra", "description": "Entra provisioning"}'
```

`201`:

```json theme={null}
{
  "id": "3f6c1e0a-...",
  "token": "nskt_9c0d...",
  "provider": "entra"
}
```

`token` is shown only in this response. Store it in your identity provider's **Secret Token** field.

### Revoke a token

`DELETE /api/settings/scim/tokens/{id}`

`204` on success. `404` with `token not found or already revoked` (plain text) otherwise. A revoked token stops working immediately.

## SCIM endpoints

Base URL: `https://<your-host>/scim/v2`. Send the token as `Authorization: Bearer <scim-token>`. Responses and errors follow [RFC 7644](https://www.rfc-editor.org/rfc/rfc7644). Errors look like this:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "404",
  "detail": "User 5b1e2c4a-... not found"
}
```

| Status | Meaning |
| - | - |
| `401` | Missing, unknown, revoked, or expired token. Includes `WWW-Authenticate: Bearer` |
| `403` | The token's provider doesn't match the active identity provider |
| `429` | More than 300 requests in a minute on this token. Retry shortly |

What the server supports (`GET /ServiceProviderConfig`): `PATCH` yes, filtering yes (up to 200 results), bulk no, sort no, ETags no, password change no.

### Users

| Request | Behavior |
| - | - |
| `GET /Users` | List. Query: `filter`, `startIndex` (1-based, default 1), `count` (default 100, max 200) |
| `GET /Users/{id}` | One user |
| `POST /Users` | Create a user with the `member` role who signs in through SSO. Email comes from `emails[0].value`, or from `userName` when it's an address. If a user with the same `externalId` exists (even one previously removed), it's restored and updated, and the response is `200` instead of `201`. `409` if the `userName` is taken |
| `PUT /Users/{id}` | Replace `userName`, email, display name (`name.formatted`), and `active` |
| `PATCH /Users/{id}` | Operations on `active`, `userName`, email, and display name |
| `DELETE /Users/{id}` | Remove the user and erase their recorded events and chat sessions. `204`. They can no longer sign in |

Setting `active` to `false` removes the user so they can no longer sign in, without erasing their data. Setting it back to `true` restores them.

Filters take one clause, `attribute operator "value"`, with operators `eq`, `co` (contains), and `sw` (starts with) on `userName`, `externalId`, `emails.value`, or `displayName`. `and`, `or`, and `not` aren't supported and return `400` with `scimType: invalidFilter`.

```bash theme={null}
curl -G https://<your-host>/scim/v2/Users \
  -H "Authorization: Bearer <scim-token>" \
  --data-urlencode 'filter=userName eq "alice@acme.com"'
```

### Groups

Each SCIM group is an org unit. Its members become the unit's directory-synced members, and their roles are recalculated.

| Request | Behavior |
| - | - |
| `GET /Groups` | List. Same paging and filter syntax as users, filtering on `displayName` or `externalId` |
| `GET /Groups/{id}` | One group with its members |
| `POST /Groups` | Create an org unit from `displayName`, `externalId`, and `members`. If a group with the same `externalId` exists, it's restored and its members replaced, and the response is `200` |
| `PUT /Groups/{id}` | Replace the name and the full member list |
| `PATCH /Groups/{id}` | Add or remove members, or rename |
| `DELETE /Groups/{id}` | Remove the org unit and its directory-synced memberships. `204` |

A member `value` can be the Nasiko user ID from a SCIM response, or the user's ID in your identity provider. Memberships added by hand in Nasiko are never changed by SCIM.


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