Provision users with SCIM
Connect your identity provider to create, update, and deactivate Joring accounts and groups automatically.
Joring implements SCIM 2.0 (RFC 7643 and 7644) for Users and Groups. Once connected, your identity provider is the source of truth for who has a Joring account and which groups they are in; the roles you assign on those groups then follow membership.
SCIM is an Enterprise feature. Setup guides: Okta and Microsoft Entra ID.
Connect your directory
In Settings → SCIM, create a connection. You get two values to paste into your identity provider:
| Base URL | https://api.joring.ai/scim/v2/{connection_id} |
| Bearer token | Begins jor_scim_ |
The token is shown once, at creation. Joring stores only a hash of it, so a lost token is rotated rather than recovered. Create a new one, update your IdP, then revoke the old one. Doing it in that order avoids a provisioning gap.
Tokens can be created with an expiration (90 days, 180 days, or 1 year) or without one. Expiration is fixed at creation; to change it, rotate. The Tokens tab warns when a token expires within 30 days.
What Joring supports
| Capability | Support |
|---|---|
| Users | Create, read, update (PUT and PATCH), deactivate, reactivate, delete |
| Groups | Create, read, update (PUT and PATCH), delete, membership changes. Pushed groups appear under People → Groups |
| Filtering | eq, ne, co, sw, ew, pr on the attributes below, plus and, or, not |
| Pagination | startIndex and count, up to 200 results per page |
| ETag versioning | meta.version and If-Match |
| Attribute projection | attributes and excludedAttributes |
| Enterprise User extension | Accepted and stored; the manager attribute builds the reporting chart |
Bulk operations, sorting, /Me | Not supported (advertised in ServiceProviderConfig) |
The roles attribute | Accepted but not used for role assignment; assign roles on the group under People → Groups |
User attributes
| SCIM attribute | Joring use |
|---|---|
userName | Unique identifier per connection. Filterable. |
externalId | Stored and unique per connection. Filterable. |
emails | The primary (or first) email becomes the account email. emails.value and emails[type eq "work"].value are filterable. |
name.givenName, name.familyName | First and last name. |
displayName, name.formatted | Display name, in that order of preference. |
active | Activation state. Accepts booleans and "True"/"False" strings. Filterable. |
meta.lastModified | Filterable with gt, ge, lt, le. |
Enterprise manager | Builds the reporting chart. |
groups | Read-only. Returned on every User with the groups the person belongs to; membership is changed through the Groups resource. |
Everything else (title, phoneNumbers, ...) | Stored and echoed back, not used by Joring. |
One email per user
Joring stores one email per user: the primary email, or the first one sent.
In your IdP, map only the primary or work email, and do not map additional
email types. Extra types are stored but not written back, and per-type email
updates target only the work email (emails[type eq "work"].value).
Group attributes
| SCIM attribute | Joring use |
|---|---|
displayName | Required, unique per team (case-insensitive). Filterable. A name matching a group managed in Joring takes that group over. |
externalId | Stored and unique per connection. Filterable. |
members | Member references (value is the SCIM user id). members[value eq "..."] is filterable. Nested groups are not supported. |
Groups from your directory
Groups pushed from your IdP appear under People → Groups as Synced from your connection, next to the groups managed in Joring. The IdP owns a synced group's name and membership; its description, roles, and managers are set in Joring, on the group's page. See Groups for the full model.
- Roles follow membership. Roles assigned on a synced group are held by every provisioned member and end when they leave the group. Roles stack: someone in two groups holds both groups' roles, combined with any roles granted directly in Joring. A role from a group shows as From group on the person's sheet and is removed through the group, not on the person.
- A pushed group takes over a matching group. When the
displayNamematches a group managed in Joring, the push links to that group instead of creating a second one: its members are replaced by the push, and its description, roles, and managers are kept. The takeover is recorded asteam.group.linked. - Disconnect on the group page converts a synced group back to Joring management with its members intact. The IdP's requests for that group then return 404 until it pushes the group again, which links by name as above. Settings → SCIM → Connection has Move all to Joring management for every synced group at once.
DELETE /Groups/{id}deletes the group in Joring together with its memberships, its roles, and its managers' scope. Roles the members held through it end.- Owners are never changed by SCIM. Ownership moves only by explicit transfer inside Joring.
Directory-driven role changes are recorded in the
audit log as team.member.group_roles_changed.
Reporting lines from your directory
The enterprise manager attribute syncs each person's manager into their
Joring profile, building the reporting chart automatically. The IdP owns
these links: they cannot be edited by hand in Joring, and they update on
every sync.
Synced reporting lines are informational until you decide otherwise. The Manager role is not granted by sync unless you enable Manager visibility in Settings → SCIM → Connection. With it on, everyone who currently has direct reports gets the Manager role, and future syncs grant it when someone gains their first report. Every grant is recorded in the audit log and can be removed individually; a removed grant is not re-created while the person keeps their reports. Enabling the policy needs the same authority as granting the Manager role by hand.
What create, deactivate, and delete do
Deactivate and delete are the two ways your IdP deprovisions someone; this page uses deprovision to mean either. Both retain the person's Joring account and all historical data.
- Create provisions an account. No email is sent; people sign in through your IdP as usual. If an account with the same email already exists, it is linked when that account is already a team member or its email domain is verified for your team; otherwise the create is rejected.
- Deactivate (
active: false) removes team access immediately: the membership and its seat are released, active app sessions for the team end, and CLI and desktop tokens are revoked. Deactivated people are listed as Deprovisioned in the Directory tab. Reactivating restores membership; roles granted in Joring survive deactivation, and roles from the person's groups come back with the membership. - Delete removes the SCIM record entirely: subsequent reads return 404 and the person no longer appears in the Directory tab.
- A member's own conversation text remains private and is never exposed by deprovisioning.
Check the Directory tab
Settings → SCIM → Directory lists everyone your IdP has sent, filterable by Active and Deprovisioned. This is the page to open when someone says they cannot sign in: if they are not in that list, the problem is IdP-side assignment, not Joring.
Troubleshooting
| Symptom | Meaning |
|---|---|
401 Unauthorized | Missing, revoked, or expired token, or the connection is disabled. |
403 Forbidden | The team's plan does not include SCIM. |
409 Conflict (uniqueness) | Another user already holds that userName, externalId, or email; or the group's externalId is already on the connection; or its displayName collides with a group on the team. Names are unique per team, case-insensitive. A match with a group managed in Joring links instead of conflicting; a match with another synced group conflicts. |
409 Conflict (seat limit) | The team is at its contracted seat count. |
409 Conflict (owner) | The Owner cannot be deprovisioned through SCIM; transfer ownership first. |
| User missing from Directory | The IdP never sent them; check app assignment on the IdP side. |
| Unquoted filter values in IdP logs | Not an error. Some IdPs send filter values without quotes; Joring accepts both quoted and unquoted forms. |
SCIM and SSO are independent
SCIM provisions accounts. SSO authenticates them. You can run either alone, but together the usual configuration is SCIM plus invite-only sign-in, so the directory decides membership and Joring never creates an account on its own.
Every provisioning event is recorded. See what is captured.