# Replay an IdP's SCIM sequence

Before a customer connects their identity provider, you can check how your app handles that provider's SCIM traffic. The test IdP's SCIM client simulator sends the requests a chosen identity provider sends, in its order, to one of your sandbox directories. Your app then receives the same [directory events](/directory-sync/events/) it would get from the real provider.

Replays work in **sandbox environments only**. A production environment answers [`sandbox_required`](/errors/sandbox_required/).

## Run a replay

Call `POST /v1/directories/{dir}/scim_replays` with a secret key that has the `directories:write` scope. The JSON body takes these fields:

- `idp` is the provider profile to replay: `generic`, `okta`, `entra`, `google`, `onelogin` or `jumpcloud`.
- `token` is the directory's current SCIM bearer token, shown once when the directory is created or its token is rotated. It is checked against the directory before anything is sent, and it is never returned or logged.
- `domain` (optional) is the email domain of the test users, for example `alice@example.com`. Use a verified domain of the directory's organization to keep the test users in domain. The default is `example.com`.

From the CLI, run `ohauthcat directories scim-replay <dir> --idp okta`. The CLI reads the token from `OHAUTHCAT_SCIM_TOKEN` or from a hidden prompt, so it never appears in your shell history.

## Read the result

The response is a `scim_replay` object:

| Field         | Meaning                                                                         |
| ------------- | ------------------------------------------------------------------------------- |
| `outcome`     | `passed` when every step got the answer the provider expects, else `failed`     |
| `steps`       | The steps sent, in order, each with `name`, `method`, `status` and `passed`     |
| `total_steps` | How many steps the full sequence has; a failed replay stops at its last step    |
| `failure`     | Why the replay stopped, without response bodies, tokens or user data; else null |

A `status` of `0` means no answer arrived for that step.

## What a replay changes

The sequence creates, updates and removes test users and groups in the directory, exactly as the provider would. Requests go to the directory's SCIM base URL through the same outbound protections as every other OhAuthCat request (HTTPS and public addresses only), and the SCIM server logs them like any other SCIM request. Each replay is recorded in the audit log as `directory.scim_replayed`.

You can run at most 20 replays per hour per environment. Beyond that the API answers [`rate_limited`](/errors/rate_limited/) with a `Retry-After` header.
