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 supportsResourceTypes(GET): The User and Group resource typesSchemas(GET): The User, enterprise User and Group schemasUsers(GET, POST): List seats, or create oneUsers/{id}(GET, PUT, PATCH, DELETE): Read, replace, update or end one seatGroups(GET, POST): List groups, or create oneGroups/{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 gets403 - A token with allowed IP addresses gets
403when the request comes from any other address - Provisioning requests do not use an
X-API-KEYor 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 createdexternalId: your directory’s identifier for the person, shown as the employee IDactive:trueinvites or reactivates the seat,falsedeactivates it. The strings"True"and"False"are accepted toodepartmentin the enterprise user extension- Responses also carry
id,emails(the work email) andmeta. 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 /Usersinvites the person to activate their corporate benefit. AuserNamethat already holds a seat gets409PUTorPATCHwithactive: falsedeactivates the seat;active: truebrings it backPUT /Users/{id}replaces the profile: anexternalIdleft out of the body is clearedPUT /Groups/{id}replaces the whole group: amemberslist left out empties it, which ends the seats of anyone leaving their last seat groupDELETE /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 gets409externalId: your directory’s identifier for the groupmembers: a list of{ "value": "<user id>" }objects, using theidreturned 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 "…"orexternalId eq "…" - Groups:
displayName eq "…"orexternalId 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
externalIdand the enterprisedepartmentcan be added, replaced or removedactivecan be added or replaced, but not removeduserNamecannot be changed
Groups
members:addadds,replacesets the whole list,removewith a value removes those members and without one removes everyonemembers[value eq "<user id>"]as the path removes one member. This form works withremoveonlydisplayNamecan be replaced but not removed;externalIdcan 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 gets400with noscimType)invalidValue: a value is wrong, such as auserNamethat is not an email or an unknown member id, or a seat cannot be given because the contract has ended or no licences are leftinvalidFilter: an unsupported filterinvalidPath: an unsupported PATCH pathmutability: an attempt to changeuserNameor removeactiveordisplayNameuniqueness: theuserNameor groupdisplayNamealready 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
429 on their own. If yours does not, wait for the number of seconds in Retry-After and send the request again.Related topics
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
