# SCIM concepts

Create a directory for an organization through the management API or an authorized portal session. The response of a SCIM directory includes its SCIM URL and bearer token, shown once; a [pulled or CSV directory](/directory-sync/pulled-sources/) has neither. A SCIM directory's `state` is `awaiting_first_request` until its first authenticated SCIM request, then `active`. Give those values to the customer's IdP administrator through a secure channel; keep the token out of logs and source control.

SCIM uses `/scim/v2/{directory_id}` on the SCIM host, with a directory-specific bearer token. It supports user and group resources, filtering, pagination, reads and writes. `/ServiceProviderConfig` describes actual capabilities; Bulk currently returns 501 and is advertised unsupported.

SCIM resource IDs map to OhAuthCat directory users and groups. An IdP's `externalId` is separate from the resource ID; do not use it as a global tenant-independent key. Fetch normalized directory data with the [management API](/reference/api/management/).

## Rotate without replacing the directory

`POST /v1/directories/{directory}/rotate_token` keeps the directory ID and SCIM URL. It returns the new token once; the previous token remains valid for one hour. A second rotation immediately drops the older previous token. Update the IdP promptly and verify new requests arrive.

Deleting a directory stops its tokens and deletes its stored users, groups, memberships and request log. It emits `dsync.deleted`; reconcile your application's local access explicitly rather than expecting a separate deletion event for every former user.
