---
title: "Directory sync with SCIM"
---

# Directory sync with SCIM

Provision and deprovision people and groups in Neural Inverse Govern from your identity provider with SCIM 2.0, including tokens, what deprovisioning does and how to read provisioning status.

Govern is a SCIM 2.0 service provider (RFC 7643 and RFC 7644). Your identity provider creates, updates and deactivates people and groups in Govern; SCIM groups sync into the organisation's directory groups, which roles and group mappings can use.

## Set it up

1. In the console, open **Identity Center > SCIM provisioning** and create a token. Through the API:

   ```bash
   curl -sS -X POST "$KEYSTONE_URL/api/v1/organizations/$ORG_ID/scim/tokens" \
     -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
     -d '{"description": "Okta production", "expires_in_days": 90}'
   ```

   `expires_in_days` is 1 to 365; without it the token lasts 90 days. The answer holds the token once, with its `id` and `expires_at`. Creating, listing and revoking tokens needs `scim:manage`.
2. In your identity provider's SCIM app, set the base URL to your Govern API origin followed by `/scim/v2` and the bearer token to the value you received.
3. Assign people and push groups from the identity provider.
4. Check **Identity Center > SCIM provisioning** for the status (below).

Rotate a token before it expires by creating a new one, switching the identity provider to it, and revoking the old one with `DELETE /api/v1/organizations/{org_id}/scim/tokens/{token_id}`. Revocation is immediate.

## Endpoints

| Resource | Routes |
|---|---|
| Users | `GET`, `POST /scim/v2/Users`; `GET`, `PUT`, `PATCH`, `DELETE /scim/v2/Users/{id}` |
| Groups | `GET`, `POST /scim/v2/Groups`; `GET`, `PUT`, `PATCH`, `DELETE /scim/v2/Groups/{id}` |
| Discovery | `GET /scim/v2/ServiceProviderConfig`, `GET /scim/v2/Schemas`, `GET /scim/v2/Schemas/{id}` |

Lists take `filter`, `startIndex` and `count`. Filters support `eq`, `ne`, `co`, `sw`, `ew`, `gt`, `ge`, `lt`, `le` and `pr`.

## What deprovisioning does

A deactivation (`active: false`) or a delete is processed before the SCIM response is returned:

1. The login is suspended.
2. Its sessions and refresh tokens end.
3. Its API keys and access keys are set inactive.
4. The role bindings that came from Identity Center group mappings are removed.
5. Every role binding of the person in the organisation is revoked and their just-in-time activations end.

Each step is timed, and a failed step is retried every 30 seconds. A deprovisioned person leaves a tombstone that just-in-time provisioning through SSO never overrides.

## Authority

While a SCIM token is active, SCIM is authoritative for the people and groups it manages: it decides their profile and groups, and sign-in through a connection does not change them. Identity Center reports this as `ScimAuthoritative` on the group mapping and JIT pages. SCIM also adopts people who were created earlier by just-in-time sign-in.

## Provisioning status

`GET /api/v1/organizations/{org_id}/scim/status` (`scim:read`) answers what the console shows:

```json
{
  "state": "healthy",
  "active_tokens": 1,
  "tokens_expiring_soon": 0,
  "last_request_at": "2026-10-10T08:58:12Z",
  "last_operation": { "operation": "patch", "resource_type": "User", "status": "succeeded", "at": "2026-10-10T08:58:12Z" },
  "last_24_hours": { "succeeded": 12, "failed": 0 },
  "recent_operations": [ { "operation": "patch", "resource_type": "User", "status": "succeeded", "at": "2026-10-10T08:58:12Z" } ]
}
```

| `state` | Meaning |
|---|---|
| `not_set_up` | No active token |
| `waiting` | A token is active, but no identity provider has used one yet |
| `failing` | The newest provisioning operation failed |
| `healthy` | The newest operation succeeded |

`tokens_expiring_soon` counts active tokens that expire within 14 days. `recent_operations` lists the newest 20 operations without their attributes or error text. `GET .../scim/tokens` lists tokens with their status (`active`, `expired` or `revoked`), never the token itself.

## Audit

Creating and revoking tokens is audited (for example `scim.token.created`), and every SCIM change goes to the audit log. See [Audit log](https://neuralinverse.com/docs/govern/audit/).

## Next

[Permission sets and group mappings](https://neuralinverse.com/docs/govern/group-mappings/) turn SCIM groups into roles.