multi-router.aidocs

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.

List usersbash
curl https://api.multi-router.ai/scim/v2/acc_7Tq2Wd9KxP/Users?count=50 \
  -H "Authorization: Bearer $MR_SCIM_TOKEN"

Endpoints

The endpoint serves these paths under the base URL:

PathMethods
/ServiceProviderConfigGET
/ResourceTypesGET
/SchemasGET
/UsersGET, POST
/Users/{id}GET, PUT, PATCH, DELETE
/GroupsGET, 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:

AttributeUse
userNameRequired, up to 320 characters. Stored in lowercase.
emailsThe primary email, or the first, is the person's email. With no emails, the userName is used.
displayNameThe person's display name. Without it, name.formatted, then the email.
externalIdThe directory's id for the person, up to 256 characters.
activefalse suspends the person. Accepts true and false as booleans or strings.
name.givenNameGiven name.
name.familyNameFamily name.
titleMatched by Title rules.
userTypeMatched by User type rules.
departmentEnterprise extension. Matched by Department rules.
divisionEnterprise extension. Matched by Division rules.
organizationEnterprise extension. Matched by Organization rules.
costCenterEnterprise extension. Matched by Cost center rules.
employeeNumberEnterprise 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.

Filter by usernametext
GET /Users?filter=userName eq "dana@example.com"

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:

PathExample
A work emailemails[type eq "work"].value
A name partname.givenName
An enterprise attributeurn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
Activeactive

On Groups, PATCH changes the display name and external id, and adds, replaces or removes members, returning 204:

Remove a group memberjson
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "remove", "path": "members[value eq \"scusr_3Hn8Wq2LdK\"]" }
  ]
}

Limits

The endpoint applies these limits:

LimitValue
Requests per directory token600 per minute
Requests with a missing or unknown token, per network1,200 per minute
Page size100
Request body1 MiB
Enabled directory tokens2

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:

StatusDetailscimTypeCause
401invalid bearer tokenThe token is missing, unknown, disabled or for another account, or provisioning is off.
400invalid JSONThe body is not valid JSON.
400invalid UserA User body is missing userName or has invalid values.
400invalid GroupA Group body has invalid values.
400unsupported filterinvalidFilterA filter other than eq on a supported attribute.
400invalid startIndexstartIndex is below 1.
400invalid countcount is above 100.
400unsupported list parameterA list parameter outside the supported ones.
400invalid PATCH operationsinvalidPathThe Operations list is empty, too long or malformed.
400required attribute cannot be removedinvalidPathA PATCH removes userName or emails.
400unsupported PATCH pathinvalidPathA Group PATCH path outside the supported ones.
403directory cannot suspend account ownerA deactivation or deletion of the account owner.
404not foundThe user or group is absent, or a group member is still to be provisioned.
405operation not availableA write while provisioning is still being turned on.
409directory identity changed; retryThe request's external id, email and username point to different existing users, or another change to the same person happened at the same time.
413request too largeThe body is larger than 1 MiB.
415unsupported content typeThe request is not JSON.
429rate limit exceededOver the rate limit.
503directory temporarily unavailableMulti-Router could not complete the request. The identity provider retries.
LifecycleTroubleshooting
Was this helpful?