User Provisioning (SCIM)
SCIM EndpointEnterprise
The SCIM 2.0 resources, attributes, filters, PATCH operations, limits and errors Multi-Router supports.
Multi-Router's SCIM endpoint implements SCIM 2.0 for Users and Groups. Identity providers call it on their own, so this page serves teams that check compatibility or connect a directory other than Okta. Every request carries a directory token and uses the account's SCIM base URL.
Authentication
Each request sends the directory token in the Authorization header, as Bearer mr_scim_… or the token on its own. Responses use application/scim+json, and requests send application/scim+json or application/json.
Endpoints
The endpoint serves these paths under the base URL:
| Path | Methods |
|---|---|
/ServiceProviderConfig | GET |
/ResourceTypes | GET |
/Schemas | GET |
/Users | GET, POST |
/Users/{id} | GET, PUT, PATCH, DELETE |
/Groups | GET, POST |
/Groups/{id} | GET, PUT, PATCH, DELETE |
Creating a user that already exists, matched by external id, email or username, updates it and returns 200; a new user returns 201. Deleting a user suspends the person in Multi-Router and returns 204; the user then returns 404 and leaves lists, and creating it again restores it. Group lists leave out members, and a single group includes them. List requests accept filter, startIndex, count, attributes and excludedAttributes, and return every attribute.
User attributes
Multi-Router reads these User attributes:
| Attribute | Use |
|---|---|
userName | Required, up to 320 characters. Stored in lowercase. |
emails | The primary email, or the first, is the person's email. With no emails, the userName is used. |
displayName | The person's display name. Without it, name.formatted, then the email. |
externalId | The directory's id for the person, up to 256 characters. |
active | false suspends the person. Accepts true and false as booleans or strings. |
name.givenName | Given name. |
name.familyName | Family name. |
title | Matched by Title rules. |
userType | Matched by User type rules. |
department | Enterprise extension. Matched by Department rules. |
division | Enterprise extension. Matched by Division rules. |
organization | Enterprise extension. Matched by Organization rules. |
costCenter | Enterprise extension. Matched by Cost center rules. |
employeeNumber | Enterprise extension. |
Group membership is sent through Groups, with each member's SCIM id, the id value Multi-Router returned for the user, such as scusr_3Hn8Wq2LdK. Every member must exist as a user before the group lists them.
Filtering and paging
List requests accept a filter with the eq operator and a quoted value, on id, externalId and userName for Users, and id, externalId and displayName for Groups, written exactly in that case. Paging uses startIndex from 1 and count up to 100.
PATCH
PATCH accepts the operations add, replace and remove, 1 to 20 per request. On Users, operations without a path set the attributes above, and paths name the attributes above, such as these; Multi-Router applies the paths it reads and returns 200:
| Path | Example |
|---|---|
| A work email | emails[type eq "work"].value |
| A name part | name.givenName |
| An enterprise attribute | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department |
| Active | active |
On Groups, PATCH changes the display name and external id, and adds, replaces or removes members, returning 204:
Limits
The endpoint applies these limits:
| Limit | Value |
|---|---|
| Requests per directory token | 600 per minute |
| Requests with a missing or unknown token, per network | 1,200 per minute |
| Page size | 100 |
| Request body | 1 MiB |
| Enabled directory tokens | 2 |
A request over the rate limit receives 429 with Retry-After: 60, and identity providers retry it on their own.
Errors
Errors use the SCIM error format with a status, a detail and, for some, a scimType:
| Status | Detail | scimType | Cause |
|---|---|---|---|
| 401 | invalid bearer token | The token is missing, unknown, disabled or for another account, or provisioning is off. | |
| 400 | invalid JSON | The body is not valid JSON. | |
| 400 | invalid User | A User body is missing userName or has invalid values. | |
| 400 | invalid Group | A Group body has invalid values. | |
| 400 | unsupported filter | invalidFilter | A filter other than eq on a supported attribute. |
| 400 | invalid startIndex | startIndex is below 1. | |
| 400 | invalid count | count is above 100. | |
| 400 | unsupported list parameter | A list parameter outside the supported ones. | |
| 400 | invalid PATCH operations | invalidPath | The Operations list is empty, too long or malformed. |
| 400 | required attribute cannot be removed | invalidPath | A PATCH removes userName or emails. |
| 400 | unsupported PATCH path | invalidPath | A Group PATCH path outside the supported ones. |
| 403 | directory cannot suspend account owner | A deactivation or deletion of the account owner. | |
| 404 | not found | The user or group is absent, or a group member is still to be provisioned. | |
| 405 | operation not available | A write while provisioning is still being turned on. | |
| 409 | directory identity changed; retry | The request's external id, email and username point to different existing users, or another change to the same person happened at the same time. | |
| 413 | request too large | The body is larger than 1 MiB. | |
| 415 | unsupported content type | The request is not JSON. | |
| 429 | rate limit exceeded | Over the rate limit. | |
| 503 | directory temporarily unavailable | Multi-Router could not complete the request. The identity provider retries. |