SCIM Provisioning
SCIM (System for Cross‑domain Identity Management) is an open standard for automating user and group provisioning between identity providers (IdPs) and service providers (SPs). With SCIM, your IdP can create, update, and deprovision users and groups in this app automatically.
Base URL
All SCIM endpoints are served under /scim/v2.
- Example:
https://your-domain.example.com/scim/v2/Users
Authentication
All SCIM endpoints require an Authorization header with an API token.
- Header:
Authorization: Bearer <YOUR_API_TOKEN> - Generate API tokens from Admin > API Tokens. See API Tokens for details.
- For step-by-step SCIM setup guides with Okta or JumpCloud, see SCIM Provisioning.
- On failure, endpoints return a SCIM‑formatted error with
401andWWW-Authenticate: Bearer.
Bearer is the only supported scheme. If your IdP offers to configure itself from ServiceProviderConfig, select OAuth Bearer Token.
Supported Resources
Service Provider Discovery
-
GET /scim/v2/ServiceProviderConfig- Returns supported SCIM features (PATCH supported, FILTER supported, BULK not supported, etc.) and advertised auth schemes.
-
GET /scim/v2/ResourceTypes- Lists resource types supported by this service:
UserandGroup.
- Lists resource types supported by this service:
-
GET /scim/v2/Schemas- Returns the SCIM schemas for
UserandGroupused by the service.
- Returns the SCIM schemas for
Users
-
GET /scim/v2/Users- Query params:
startIndex(default1),count(default100),filter. - Supported filter:
userName eq "<email>"anduserName sw "<prefix>". - Returns SCIM ListResponse of Users.
- Query params:
-
POST /scim/v2/Users- Creates a user. Extracts the email and
name.formattedordisplayName(fallback togivenName + familyNameoruserName). The entry inemailswithprimary: true(or the first entry) is the primary email and every other entry becomes an alias. - Response:
201 Createdwith SCIM User.
- Creates a user. Extracts the email and
-
GET /scim/v2/Users/{id}- Fetches a specific user by
id. The implementation attempts lookup by email and by id.
- Fetches a specific user by
-
PATCH /scim/v2/Users/{id}- Supports
replaceoperations forname.formatted,displayName,userName, andemails[type eq "work"].value, plusadd,replace, andremoveon filtered email paths such asemails[type eq "other"].valuefor aliases. - Also accepts direct payloads with
name.formatted/displayNameanduserName/emails[0].valueif not using SCIMOperations.
- Supports
-
DELETE /scim/v2/Users/{id}- Deletes a user. Returns
204 No Contenton success.
- Deletes a user. Returns
Groups
-
GET /scim/v2/Groups- Query params:
startIndex,count,filter. - Supported filters: a single comparison on
displayName,externalId, orid, usingeqorsw, with the value in single or double quotes. For example,externalId eq "<id>". - Any other filter, such as
and/orcombinations or other attributes, returns400withscimTypeinvalidFilterinstead of the full group list. - Returns SCIM ListResponse of Groups with
members. Users that have been deactivated (active: false) are not listed as members.
- Query params:
-
POST /scim/v2/Groups- Creates a group with
displayName. Ifmembersare provided, it will setuser_idsvia a follow‑up call. - Response:
201 Createdwith SCIM Group.
- Creates a group with
-
GET /scim/v2/Groups/{id}- Fetches a specific group.
-
PATCH /scim/v2/Groups/{id}- Supports
replaceondisplayNameand fullmembersreplacement. - Supports
addandremoveonmembersincluding path expressionsmembers[value eq "<userId>"].
- Supports
-
DELETE /scim/v2/Groups/{id}- Deletes a group. Returns
204 No Contenton success.
- Deletes a group. Returns
Request and Response Examples
Below are minimal examples tailored to what the service accepts and returns.
Auth header example
curl -s -H "Authorization: Bearer $WILLOW_API_TOKEN" https://your-domain.example.com/scim/v2/ServiceProviderConfig
Create User
Request:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "jane.doe@example.com",
"name": { "formatted": "Jane Doe", "givenName": "Jane", "familyName": "Doe" },
"displayName": "Jane Doe",
"emails": [
{ "value": "jane.doe@example.com", "type": "work", "primary": true }
],
"active": true
}
Response (201):
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "<user-id>",
"externalId": "<user-id>",
"userName": "jane.doe@example.com",
"name": { "formatted": "Jane Doe", "givenName": "Jane", "familyName": "Doe" },
"displayName": "Jane Doe",
"emails": [
{ "value": "jane.doe@example.com", "type": "work", "primary": true }
],
"active": true,
"meta": {
"resourceType": "User",
"created": "<iso>",
"lastModified": "<iso>",
"location": "https://your-domain.example.com/scim/v2/Users/<user-id>"
}
}
Filter Users by userName
curl -s \
-H "Authorization: Bearer $WILLOW_API_TOKEN" \
"https://your-domain.example.com/scim/v2/Users?filter=userName%20eq%20%5C"jane.doe@example.com%5C""
Patch User email
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "replace",
"path": "emails[type eq \"work\"].value",
"value": "jane.new@example.com"
}
]
}
Create Group with members
Request:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Developers",
"members": [{ "value": "<user-id-1>" }, { "value": "<user-id-2>" }]
}
Patch Group members (add)
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{ "op": "add", "path": "members", "value": [{ "value": "<user-id-3>" }] }
]
}
Error format
Errors follow SCIM Error schema:
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "<message>",
"status": "<http-status-as-string>"
}
Notes and Limitations
- Bulk operations are not supported.
- Sorting is not supported; filtering is limited to the expressions shown above.
activeis stored with the user's SCIM data and returned byGET /scim/v2/Users. Settingactivetofalseends the user's session and blocks access, but keeps the user and their group memberships so a reactivated user gets their groups back. Group responses (GET,POST,PATCH,PUT) leave deactivated users out ofmembers.- Group membership updates are performed via an internal mapping and reflected in the SCIM
membersproperty.
Mapping Overview
- User
idandexternalIdmap to the internal user id;userNameand the primary entry inemailsmap to the internal email.
Email aliases
A user can hold more than one email.
GETreturns every email: the primary first withprimary: true, then each alias.POST,PUT, andPATCHaccept more than one entry inemails. The flagged entry, or the first one, is the primary. The rest become aliases.- A sync replaces only the aliases the IdP sent before. Aliases an admin added by hand are kept.
- No two users in the organization can share an address. A request that would reuse another user's email returns
409withscimTypeuniqueness.
To send a secondary email from Okta, see Sync a secondary email.
- Group
displayNamemaps to internalname;members[].valuemaps to internaluser_ids.