SCIM 2.0 reference

Claresia exposes a SCIM 2.0 endpoint per tenant. Your IdP (Okta, Azure AD, Google Workspace, OneLogin, JumpCloud, Keycloak) pushes user create / update / delete events. Claresia provisions, updates, and de-provisions in real time.

Endpoint

Per-tenant URL pattern:

https://api.workos.com/scim/v2/<directory_id>

The exact URL + bearer token are displayed in Step 5 of the Onboarding Portal.

Supported resources

Resource	Operations	Notes
Users	GET / POST / PATCH / PUT / DELETE	DELETE = active: false (de-provision). Hard-delete on tenant offboarding only.
Groups	GET / POST / PATCH / PUT / DELETE	Group membership drives RBAC role assignment
Schemas	GET	RFC 7644 standard
ServiceProviderConfig	GET	Capabilities advertisement
ResourceTypes	GET	Standard

Supported user attributes

SCIM attribute	Claresia field	Required
userName	email (also primary lookup)	yes
name.givenName	first_name	yes
name.familyName	last_name	yes
emails[type=work].value	email (canonical)	yes
active	is_active (false = de-provisioned)	yes
title	job_title (drives archetype mapping via cc-061)	recommended
department	department	optional
phoneNumbers[type=work].value	phone	optional
addresses[type=work]	office_location	optional
preferredLanguage	locale (e.g., en-US, it-IT)	optional
timezone	timezone (IANA, e.g., Europe/Rome)	optional

Custom attributes (Enterprise extension)

Attribute	Use
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber	Cross-system employee lookup
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value	Manager hierarchy (drives manager dashboards)
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter	Cost-center reporting

Group attributes

SCIM attribute	Claresia field
displayName	group_name
members[]	group_member_user_ids[]

Groups starting with the prefix claresia- are recognized as RBAC role groups (see Identity overview).

De-provisioning behavior

When your IdP sends PATCH /Users/{id} with active: false:

1. Claresia marks the user is_active = false in our DB
2. We revoke the user’s JWT immediately — subsequent API calls return 401
3. We remove them from every per-archetype skill entitlement set
4. We trigger a publish refresh to the LLM platform Distribution Plane — within 60s, the user cannot invoke any Claresia skill from Claude / Copilot / ChatGPT / Slack
5. We write a governance_event Hub record user_deactivated (actor: <idp_name>:scim)

End-to-end de-provision SLO: <60 seconds from your IdP’s webhook to the user losing skill access.

Pagination + filtering

We support standard SCIM 2.0 pagination + filtering:

• ?startIndex=1&count=100
• ?filter=userName eq "alice@dainese.it"
• ?filter=active eq true
• ?filter=title sw "Sr " (starts-with on title — useful to test archetype mapping)

Rate limits

• 100 requests / second per tenant (sustained)
• 1000 requests / second per tenant (burst, 10s window)

If your IdP triggers a full-org sync, requests stay within these limits — for

50k users, contact your CSM to coordinate the initial sync.

Webhook callbacks (optional)

For IdPs that don’t poll, Claresia can register a webhook on user-lifecycle events to your endpoint. Events:

• user.created
• user.updated
• user.deactivated
• user.skill_entitlement_changed
• user.archetype_assigned

Webhook payloads are signed with HMAC-SHA256 (header X-Claresia-Signature). Idempotent retry on 5xx with exponential backoff up to 24h.

Testing your SCIM integration

Use the Sync now button in Onboarding Portal Step 5 — it triggers an immediate full-pull from your IdP and shows you:

• Users created
• Users updated
• Users de-provisioned
• Groups created / updated
• Errors (with HTTP status + body)

If you see errors, paste the error code into Slack/Teams Connect — your CSM has a runbook for every SCIM error.

Compliance notes

• SCIM bearer tokens are per-tenant, immutable, rotatable
• Tokens are stored hashed in our DB (we cannot retrieve a token after generation; rotation generates a new one)
• All SCIM traffic is TLS 1.3 minimum
• IP allowlisting available in Mode B/C — restrict the SCIM endpoint to your IdP’s egress IP ranges