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

# Manage SCIM

> Rotate the SCIM token, pause and resume provisioning, turn on SCIM only, read the mismatch report and turn SCIM off.

Manage SCIM in the **SCIM provisioning** section of [**Settings > Single sign-on**](https://app.sazabi.com/settings/single-sign-on), with `sazabi sso scim`, or with Terraform. Everything here needs an **owner**, or a secret key with permission to manage SSO (`can_manage_sso`), unless a section says otherwise.

## Rotate the token

Click **Rotate token**, or run `sazabi sso scim rotate-token`. `--expires-at` sets the new token's expiry.

You get a new token, shown once. The previous token keeps working for **24 hours**, or until its own expiry if that comes sooner, so you can update your IdP without a gap; it shows as **Retiring** in the token list.

A connection holds at most **two** live tokens: the current one and the one retiring. Rotating again while a retiring token is still live is refused ("Wait for the previous token to expire before you rotate again.").

## See SCIM's state

The **SCIM provisioning** section shows **Last change received** and each live token's prefix, when it was created, when it expires and when it was last used. Each token is marked **Current**, **Retiring** or **Expires soon**. From the CLI, run `sazabi sso scim status`.

### Last change received

The **SCIM provisioning** section of [**Settings > Single sign-on**](https://app.sazabi.com/settings/single-sign-on) shows **Last change received**: when your IdP last created, updated or deactivated someone. `sazabi sso scim status` shows it as `Last change`, and Terraform's [sazabi\_sso\_scim](https://docs.sazabi.com/reference/terraform/sazabi_sso_scim.md) as `last_change_at`. Lookups don't count as changes.

## Turn SCIM only on or off

By default, someone your IdP lets sign in to Sazabi but hasn't pushed yet is added on their first sign-in, if **Add people on their first sign-in** is on. **SCIM only** makes your IdP's pushes the only way in: a person must have a SCIM record before their first sign-in. See [SCIM provisioning](https://docs.sazabi.com/guides/administer/single-sign-on/scim.md#scim-only).

SCIM only is a connection setting. On [**Settings > Single sign-on**](https://app.sazabi.com/settings/single-sign-on), turn on the **SCIM only** switch in the **SCIM provisioning** section and confirm, or turn it off. From the CLI, pass your connection's protocol (`saml` or `oidc`), which `sazabi sso connect` always needs:

```bash theme={"system"}
sazabi sso connect --protocol saml --enable-scim-only
sazabi sso connect --protocol saml --disable-scim-only
```

or with the `scim_only` argument of [sazabi\_sso\_connection](https://docs.sazabi.com/reference/terraform/sazabi_sso_connection.md) in Terraform.

SCIM only needs SCIM on, so turning it on while SCIM is off is refused. While it's on, turning SCIM off is refused; turn SCIM only off first. Otherwise nobody new could ever sign in.

## Safety limits

An IdP misconfiguration, such as a changed assignment rule, can deactivate everyone at once. Sazabi limits how many people SCIM can remove in an hour, and limits what a leaked SCIM token can reach.

### The bulk-deactivation pause

Deactivations through your connection are counted over a rolling hour. By default the limit is the larger of **10** and **10%** of the connection's active SCIM records. The deactivation that would go over it is refused, and SCIM is **paused**:

* Every SCIM write, including creates and updates, answers `503` with `Retry-After`. Lookups still work.
* Every owner gets a **SCIM paused** email.
* Nobody else is removed until an owner resumes SCIM.

IdPs treat a `503` as Sazabi's failure and retry it, so no person is marked as failed for good. Check your IdP's recent changes, then resume SCIM. To resume SCIM, pause it yourself or change the threshold, see [Pause and resume SCIM](#pause-and-resume-scim).

### What the token can do

A SCIM token:

* belongs to one connection, so it reaches only your organization, and only that connection's SCIM records;
* can only read and write SCIM Users. It can't sign anyone in, and it isn't an API key for anything else;
* is stored as a hash, and shown only when it's created;
* allows **600 requests a minute**; more answer `429` with `Retry-After`;
* stops working when it's revoked or expires, when SCIM is turned off, when the connection is deleted or its **Allow sign-in** is turned off, or when the organization is deleted or suspended.

Sazabi records each token's last use and the address it came from; the **SCIM provisioning** section and `sazabi sso scim status` show them. Rotate a token you think has leaked. See [Rotate the token](#rotate-the-token). There's no IP allowlist for the token, because Entra ID's provisioning service has no small, fixed set of addresses.

## Pause and resume SCIM

SCIM pauses itself when your IdP deactivates too many people in an hour. See [Safety limits](#safety-limits). While SCIM is paused, the **SCIM provisioning** section shows **SCIM is paused** and, for owners, a **Resume SCIM** button. Pausing SCIM yourself and setting the threshold have no dashboard or CLI control; use the [Sazabi API](https://docs.sazabi.com/reference/api.md) for those, or for resuming, as an owner or with a `can_manage_sso` secret key:

```bash theme={"system"}
curl -X POST https://api.sazabi.com/v1/sso/scim/pause \
  -H "Authorization: Bearer $SAZABI_API_KEY"
curl -X POST https://api.sazabi.com/v1/sso/scim/resume \
  -H "Authorization: Bearer $SAZABI_API_KEY"
```

Pause SCIM yourself while you fix an IdP rule, for example. Before you resume, check your IdP's recent changes. Every owner gets a **SCIM paused** or **SCIM resumed** email. The hour's count starts again from the resume, so your IdP's retries go through. Entra ID retries on its own in its next cycle; in Okta, retry the failed tasks from the app's provisioning errors.

## Set the deactivation threshold

A planned mass offboarding needs a higher threshold first, or a resume after each pause. Set the connection's threshold, from 1 to 100,000 deactivations an hour:

```bash theme={"system"}
curl -X POST https://api.sazabi.com/v1/sso/scim/threshold \
  -H "Authorization: Bearer $SAZABI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold": 250}'
```

Send `{"threshold": null}` to go back to the default. Every owner gets a **SCIM deactivation threshold changed** email.

## Watch for problems

Sazabi doesn't poll your IdP for its full list of people. Okta and Entra ID send nothing when nothing changes, so silence alone is normal. These signals show when silence isn't.

### The quiet-IdP alert

Every owner gets an **Identity provider stopped sending SCIM changes** email when both are true:

* your IdP has sent no SCIM request for **7 days**, counted from when SCIM was last turned on if it has never sent one since; and
* someone has signed in through your connection since then with no SCIM record.

That combination usually means provisioning stopped at your IdP, for example because the token expired there or provisioning was turned off. Owners get one email per quiet stretch; the next request from your IdP ends it.

### The mismatch report

The mismatch report lists, for your connection with SCIM on:

* **Signed in without a SCIM record:** members who signed in through the connection in the last **30 days** and have no SCIM record. They joined on first sign-in, or their subject and `externalId` don't match.
* **SCIM records that never signed in:** active SCIM records whose person has never signed in through the connection.

Each list holds up to 500 people, and says when it was cut short. A member's latest sign-in can be up to an hour behind. Owners and admins open it with **Review mismatches** in the **SCIM provisioning** section, which shows both lists in a **SCIM mismatches** dialog, or get it from the API:

```bash theme={"system"}
curl https://api.sazabi.com/v1/sso/scim/mismatch-report \
  -H "Authorization: Bearer $SAZABI_API_KEY"
```

### The SCIM member list

The SCIM member list shows every member with a SCIM record, with their role, `userName`, `externalId` and whether the record is active. It includes members whose SCIM record outlived SCIM: each one's `connectionState` is `live`, `scim_off` or `deleted`. After you turn SCIM off or delete the connection, use it to review whom to remove by hand.

```bash theme={"system"}
curl "https://api.sazabi.com/v1/sso/scim/members?limit=100" \
  -H "Authorization: Bearer $SAZABI_API_KEY"
```

Pass the answer's `nextCursor` as `cursor` for the next page.

### Token expiry reminders

If the current SCIM token has an expiry, every owner gets a **SCIM token expires soon** email 14 days before it expires and again 1 day before. A token retiring after a rotation expires on purpose, so it sends none. See [Rotate the token](#rotate-the-token).

## Turn SCIM off

Click **Turn off SCIM** and confirm, or run `sazabi sso scim disable` (it asks for confirmation; pass `--yes` to skip it). Turning SCIM off revokes every SCIM token at once. Members and their SCIM records are kept, but people who leave your IdP are no longer removed automatically. Remove them yourself; the [SCIM member list](#the-scim-member-list) shows who SCIM added.

Turning SCIM off is refused while [SCIM only](https://docs.sazabi.com/guides/administer/single-sign-on/scim.md#scim-only) is on. Turn SCIM only off first. Deleting the SSO connection also turns SCIM off.

## Manage SCIM with Terraform

The [sazabi\_sso\_scim](https://docs.sazabi.com/reference/terraform/sazabi_sso_scim.md) resource turns SCIM on and holds the token in state as a sensitive value:

```hcl theme={"system"}
resource "sazabi_sso_scim" "example" {
  rotation_trigger = "2026-q4"
  depends_on       = [sazabi_sso_connection.example]
}
```

Change `rotation_trigger` to rotate the token; the previous one keeps working for 24 hours, or until its own expiry if that comes sooner. `token_expires_at` sets the expiry of each token it mints. Destroying the resource turns SCIM off. Creating it fails if SCIM is already on, because Terraform can't read back a token it didn't mint. Import it instead (`terraform import sazabi_sso_scim.example -`): Terraform holds the live token by its ID without its value and doesn't rotate it, so your identity provider keeps working. The first apply after import never rotates: any `rotation_trigger` in the configuration at that apply is recorded as the baseline, and `terraform plan` warns. The exception is when no live token is held (none at import, or the held one was revoked or expired before that apply): that apply mints one, with no baseline warning. After that first apply, changing `rotation_trigger` rotates as usual.

## Verify SCIM is on

On [**Settings > Single sign-on**](https://app.sazabi.com/settings/single-sign-on), the **SCIM provisioning** section shows one token marked **Current**, or `sazabi sso scim status` shows `Status on`. After your IdP sends its first change, **Last change received** shows when.

## Further reading

> [card] [SCIM provisioning](https://docs.sazabi.com/guides/administer/single-sign-on/scim.md)
>
> Matching, deactivation and SCIM only.


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