Concepts
What is SCIM?
SSO answers who is signing in. SCIM answers who exists at all. It is the protocol an identity provider uses to tell your application that somebody joined, changed team or left the company — which is the difference between a user list that is accurate and one that is merely historical.
The idea in one paragraph
SCIM — System for Cross-domain Identity Management — is a small REST API with a fixed schema. The customer's identity provider is the client; your application is the server. When something changes in their directory, they call you.
That is the whole model. There is no polling, no nightly CSV, no admin re-entering names. A person is created in the directory and, seconds later, exists in your product with the right email and the right groups.
The reason it matters commercially is the reverse direction. When someone leaves, an SSO-only integration means they can no longer sign in — but their account, their API tokens and their data access all remain. SCIM is what actually deprovisions them, and it is why security reviews ask for it by name.
What the provider sends
A SCIM client uses ordinary HTTP verbs against two resource types, Users and Groups. If you implement the server yourself, these are the calls you must answer.
| Operation | Meaning | What your product does |
|---|---|---|
| POST /Users | Someone joined or was assigned your app | Create the account, usually inactive until first sign-in |
| PATCH /Users/:id | An attribute changed | Update the field; a change to active is a suspension |
| PUT /Users/:id | Full replacement of the record | Apply the whole record as sent |
| DELETE /Users/:id | Removed from your app or from the company | Deactivate rather than delete, in most products |
| POST /Groups | A group was assigned to your app | Create the group and its membership |
| PATCH /Groups/:id | Membership changed | Add or remove members, and re-evaluate roles |
What you handle with Paycux
Directory Sync runs the SCIM server for you. The customer's IT admin is given an endpoint URL and a bearer token, their provider talks SCIM to Paycux, and your application receives ordinary webhooks with a normalised shape.
That removes the two hardest parts of implementing SCIM yourself: the schema differences between providers, and the PATCH operation syntax, which is genuinely awkward and implemented inconsistently in the wild.
1{2 "id": "event_01HQZX8N4T",3 "event": "dsync.user.updated",4 "createdAt": "2026-04-18T09:12:44Z",5 "data": {6 "id": "directory_user_01HQZX8N4T",7 "directoryId": "directory_01HQZX8N4T",8 "organizationId": "org_01HQZX8N4T",9 "idpId": "00u1a2b3c4d5e6f7g8h9",10 "firstName": "Avery",11 "lastName": "Lindqvist",12 "emails": [{ "primary": true, "value": "avery@foo-corp.example" }],13 "state": "active",14 "groups": [{ "id": "directory_group_01HQZX8N4T", "name": "Engineering" }]15 }16}
Writing a handler that survives
Directory events are a stream from a system you do not control. Three habits make the difference between a handler that works in testing and one that works after a customer's Monday morning bulk import.
- 1Treat every event as the desired end state, not as an instruction. Upsert the whole record rather than applying a diff, and an out-of-order delivery stops mattering.
- 2Deduplicate on the event ID. Retries are normal, and a handler that sends a welcome email twice will be noticed.
- 3Return quickly. Acknowledge the delivery, then do the slow work on a queue — a provider that times out will retry, which amplifies whatever is already slow.
Deactivate, do not delete. A deletion event usually means the person left the company, and destroying their authored content along with their account is rarely what the customer meant.
Groups and what they mean
Groups arrive with the names the customer's IT team chose, which will not match your product's roles. Resist the temptation to infer: a group called Admins in one directory means something different from the same name in another.
Give an organization admin a screen that pairs each incoming group with one of your roles, store the mapping against the organization, and re-evaluate it whenever a membership event arrives. The mapping is small, explicit and easy to explain during a security review.
What SCIM does not do
SCIM carries identity, not authorisation. It tells you a person exists and which groups they are in; it has no opinion about what they may do in your product. That is your role model's job.
It is also not a sign-in protocol. A directory can provision an account for somebody who never signs in, and an SSO connection can authenticate somebody the directory never provisioned. Most enterprise deployments run both, which is why the two features are usually configured in the same sitting.