Skip to main content

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 401 and WWW-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: User and Group.
  • GET /scim/v2/Schemas

    • Returns the SCIM schemas for User and Group used by the service.

Users​

  • GET /scim/v2/Users

    • Query params: startIndex (default 1), count (default 100), filter.
    • Supported filter: userName eq "<email>" and userName sw "<prefix>".
    • Returns SCIM ListResponse of Users.
  • POST /scim/v2/Users

    • Creates a user. Extracts the email and name.formatted or displayName (fallback to givenName + familyName or userName). The entry in emails with primary: true (or the first entry) is the primary email and every other entry becomes an alias.
    • Response: 201 Created with SCIM User.
  • GET /scim/v2/Users/{id}

    • Fetches a specific user by id. The implementation attempts lookup by email and by id.
  • PATCH /scim/v2/Users/{id}

    • Supports replace operations for name.formatted, displayName, userName, and emails[type eq "work"].value, plus add, replace, and remove on filtered email paths such as emails[type eq "other"].value for aliases.
    • Also accepts direct payloads with name.formatted/displayName and userName/emails[0].value if not using SCIM Operations.
  • DELETE /scim/v2/Users/{id}

    • Deletes a user. Returns 204 No Content on success.

Groups​

  • GET /scim/v2/Groups

    • Query params: startIndex, count, filter.
    • Supported filters: a single comparison on displayName, externalId, or id, using eq or sw, with the value in single or double quotes. For example, externalId eq "<id>".
    • Any other filter, such as and/or combinations or other attributes, returns 400 with scimType invalidFilter instead of the full group list.
    • Returns SCIM ListResponse of Groups with members. Users that have been deactivated (active: false) are not listed as members.
  • POST /scim/v2/Groups

    • Creates a group with displayName. If members are provided, it will set user_ids via a follow‑up call.
    • Response: 201 Created with SCIM Group.
  • GET /scim/v2/Groups/{id}

    • Fetches a specific group.
  • PATCH /scim/v2/Groups/{id}

    • Supports replace on displayName and full members replacement.
    • Supports add and remove on members including path expressions members[value eq "<userId>"].
  • DELETE /scim/v2/Groups/{id}

    • Deletes a group. Returns 204 No Content on success.

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.
  • active is stored with the user's SCIM data and returned by GET /scim/v2/Users. Setting active to false ends 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 of members.
  • Group membership updates are performed via an internal mapping and reflected in the SCIM members property.

Mapping Overview​

  • User id and externalId map to the internal user id; userName and the primary entry in emails map to the internal email.

Email aliases​

A user can hold more than one email.

  • GET returns every email: the primary first with primary: true, then each alias.
  • POST, PUT, and PATCH accept more than one entry in emails. 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 409 with scimType uniqueness.

To send a secondary email from Okta, see Sync a secondary email.

  • Group displayName maps to internal name; members[].value maps to internal user_ids.