SCIM provisioning reference

Everything an identity provider integration needs to provision corporate seats with SCIM 2.0: the endpoints, authentication, the attributes we read, the filters and PATCH operations we accept, and the errors you may see.

Last reviewed

Base URL and endpoints

Use the SCIM base URL shown on the SCIM provisioning card in your corporate settings. It ends in /api/v1/corporate/scim/v2/, and every endpoint below is relative to it. Requests and responses are JSON, sent as application/scim+json (plain application/json is accepted too).

  • ServiceProviderConfig (GET): What the service supports
  • ResourceTypes (GET): The User and Group resource types
  • Schemas (GET): The User, enterprise User and Group schemas
  • Users (GET, POST): List seats, or create one
  • Users/{id} (GET, PUT, PATCH, DELETE): Read, replace, update or end one seat
  • Groups (GET, POST): List groups, or create one
  • Groups/{id} (GET, PUT, PATCH, DELETE): Read, replace, update or delete one group

The service does not offer bulk operations, sorting, ETags or password changes, as ServiceProviderConfig reports.

Authentication

Send the provisioning token as a bearer token on every request:

Authorization: Bearer scim_…
  • An owner creates the token on the SCIM provisioning card. It is shown once and cannot be retrieved later; we store only a hash of it
  • An organisation can hold up to 5 active tokens at once, for example one per identity provider
  • A token only ever sees and changes its own organisation’s seats and groups
  • A missing, malformed, revoked or expired token gets 401, as does a replaced token once its overlap has ended; a token whose organisation’s contract has ended gets 403
  • A token with allowed IP addresses gets 403 when the request comes from any other address
  • Provisioning requests do not use an X-API-KEY or reporting API key, and a reporting key cannot call these endpoints

Expiry and rotation

Expiry

When an owner creates a token they can give it an expiry of up to 365 days, or leave it with no expiry, which is the default. Each token on the SCIM provisioning card shows its expiry date or “No expiry”, and how old it is. An expired token stops working and is marked Expired.

  • Every owner is emailed 14 days and again 3 days before a token expires
  • A token with no expiry that has been in use for a year prompts an email suggesting you rotate it

Rotating a token

Rotate a token on a regular schedule, when someone who knew it leaves, and straight away if it may have leaked. Choose Rotate on the token in the SCIM provisioning card. You get a replacement token, shown once, with the same name and allowed IP addresses, and you choose what happens to the old one:

  • Keep the old token working for 24 hours, so you can update your identity provider without a gap. It is marked “Being replaced” until then
  • End the old token now, for a token you believe has leaked

Revoking a token stops it at once. An expired, revoked or replaced token does not count towards the limit of 5 active tokens.

Allowed IP addresses

You can lock a token to your identity provider’s network. Add allowed IP addresses when you create the token, or later with Edit IP addresses on its row. With no addresses, which is the default, the token works from anywhere; the row reads “Allowed IP addresses: any address” or how many addresses it allows.

  • Up to 20 entries, each an IPv4 or IPv6 address or a CIDR range such as 198.51.100.0/24
  • Only public addresses are accepted. Private, loopback and link-local addresses are refused, as are ranges wider than /8 (IPv4) or /32 (IPv6)
  • A request from any other address gets 403. The error says the address is not allowed but never lists the addresses that are
  • Owners are emailed when a token is refused this way, at most once a day for each token, with the address that was refused
  • Check your identity provider’s published outbound addresses before you save a list, or provisioning will stop

Recent requests on each token lists the calls made with it, including refused ones, so you can check which address your identity provider calls from.

Provisioning changes in your audit log

Every change a token makes appears in your organisation’s audit log, marked as made over SCIM, with the token’s prefix and the address the request came from:

  • Seats invited, deactivated and reactivated, and invitations withdrawn
  • Profile changes such as the employee ID or department. The log names the fields that changed, not their values
  • Groups created, renamed and deleted, and members added or removed

A request that changes nothing adds nothing to the log. Creating, rotating and revoking tokens is recorded too.

Users and groups

User attributes

  • userName (required): the employee’s work email. It cannot be changed after the seat is created
  • externalId: your directory’s identifier for the person, shown as the employee ID
  • active: true invites or reactivates the seat, false deactivates it. The strings "True" and "False" are accepted too
  • department in the enterprise user extension
  • Responses also carry id, emails (the work email) and meta. Other attributes you send, such as names, are ignored
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "alice@company.com",
  "externalId": "EMP-001",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Finance"
  }
}

What each call does to a seat

  • POST /Users invites the person to activate their corporate benefit. A userName that already holds a seat gets 409
  • PUT or PATCH with active: false deactivates the seat; active: true brings it back
  • PUT /Users/{id} replaces the profile: an externalId left out of the body is cleared
  • PUT /Groups/{id} replaces the whole group: a members list left out empties it, which ends the seats of anyone leaving their last seat group
  • DELETE /Users/{id} ends the seat. The person’s account, will and documents are never deleted, because they belong to the employee

Group attributes

  • displayName (required): unique within your organisation, so a second group with the same name gets 409
  • externalId: your directory’s identifier for the group
  • members: a list of { "value": "<user id>" } objects, using the id returned for each user. An id that is not one of your seats is refused

Groups are kept in step with your directory. Where seat groups are set up for single sign-on, adding someone to a seat group gives them a seat, and removing them from their last seat group ends it. Add excludedAttributes=members to a group read to leave the member list out.

Filters and paging

Identity providers use a filter to find an existing seat before creating one. Only an exact match on one attribute is supported:

  • Users: userName eq "…" or externalId eq "…"
  • Groups: displayName eq "…" or externalId eq "…"

Any other filter is refused with 400 and invalidFilter rather than ignored, so a filter can never silently return every seat.

Lists are paged with startIndex (from 1) and count. count defaults to 100 and is capped at 200.

PATCH operations

A PATCH body must use the PatchOp schema and carry a non-empty Operations list. Each operation is add, replace or remove. An add or replace may leave out path and send an object value instead; a remove always needs a path.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

Users

  • externalId and the enterprise department can be added, replaced or removed
  • active can be added or replaced, but not removed
  • userName cannot be changed

Groups

  • members: add adds, replace sets the whole list, remove with a value removes those members and without one removes everyone
  • members[value eq "<user id>"] as the path removes one member. This form works with remove only
  • displayName can be replaced but not removed; externalId can be replaced or removed
  • Any other path is refused with invalidPath

Errors

Every error, including authentication and rate-limit errors, uses the SCIM error body. status is the HTTP status as a string, and scimType is present when there is one.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "detail": "A seat for this userName already exists.",
  "scimType": "uniqueness"
}
  • invalidSyntax: the body is JSON but not an object, or a PATCH body is malformed (a body that is not valid JSON gets 400 with no scimType)
  • invalidValue: a value is wrong, such as a userName that is not an email or an unknown member id, or a seat cannot be given because the contract has ended or no licences are left
  • invalidFilter: an unsupported filter
  • invalidPath: an unsupported PATCH path
  • mutability: an attempt to change userName or remove active or displayName
  • uniqueness: the userName or group displayName already exists

A user or group id that does not exist in your organisation gets 404, with no scimType.

Rate limit

Each token may make 600 requests a minute, enough for an identity provider’s first full push. Over that, requests get 429 with a Retry-After header saying how many seconds to wait.

Tip

Most identity providers retry a 429 on their own. If yours does not, wait for the number of seconds in Retry-After and send the request again.

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.