Reference
SCIM provisioning
Admin API endpoints for an application's SCIM connection - settings, token, test, mapping, scope, retries and reconciliation.
Endpoints under https://acme.sovrain.net/api/v1/apps/{slug}/scim, for applications of type SCIM and SAML
applications with provisioning. Authentication and conventions are on Admin API. How provisioning
works: SCIM.
Scope: apps:read for GET, apps:write for every other call.
These endpoints differ from the rest of the API:
- Unknown fields in a body are ignored.
- Every call except
GETcreates the connection when the application has none, exceptPUT …/provisioningwithfalse(which deletes it),PUT …/tokenwith a blank token andPUT …/scimwith nothing to change (which answers404). - Errors are
400,404and422in the usual format, or500with an empty body.
The connection object
{
"enabled": true,
"base_url": "https://expenses.acme.example/v2",
"has_token": true,
"last_test_status": "ok",
"last_test_detail": null,
"paused_since": null,
"pause_reason": null,
"username_source": "EMAIL",
"options": {
"create_users": true,
"update_users": true,
"deactivate_users": true,
"deprov_behavior": "DEACTIVATE"
},
"scope_everyone": false,
"mappings": [
{ "source": "email", "path": "emails[type eq \"work\"].value" },
{ "source": "firstName", "path": "name.givenName" },
{ "source": "lastName", "path": "name.familyName" }
]
}
| Field | Default for a new connection | Notes |
|---|---|---|
enabled | false | |
base_url | null | The SCIM base URL of the application |
has_token | false | The token itself is never returned |
last_test_status | null | ok, auth_failed, timeout or error, in lower case |
last_test_detail | null | |
paused_since, pause_reason | null | Set when the application answered 401 or 403 |
username_source | EMAIL | EMAIL, LOGIN, ID or EXTERNAL_ID |
options.create_users | true | |
options.update_users | true | |
options.deactivate_users | true | When false, users are neither deactivated nor deleted, except by Remove or Force sync… on drift |
options.deprov_behavior | DEACTIVATE | DEACTIVATE or DELETE |
scope_everyone | false | |
mappings | the three shown above |
The groups and users of the scope are not returned.
Get the connection
GET /api/v1/apps/{slug}/scim
Response 200: the connection object.
Errors: 404 not_found with Not found: SCIM connection of application portal when the application has no
connection.
Change the connection
PUT /api/v1/apps/{slug}/scim
| Field | Type | Required | Notes |
|---|---|---|---|
base_url | string | no | Left out: unchanged. https only, on a public address. Sending it, even unchanged, marks the connection as not tested and stops jobs until a test passes. |
options | object | no | Left out: unchanged. Inside it, a boolean left out is false and deprov_behavior left out is DEACTIVATE. |
options.create_users | boolean | no | |
options.update_users | boolean | no | |
options.deactivate_users | boolean | no | |
options.deprov_behavior | string | no | DEACTIVATE or DELETE |
enabled | boolean | no | Left out: unchanged |
The parts are saved one after another: base_url, then options, then enabled. When one is refused, the parts
before it stay saved.
To change only the options, leave base_url out.
{
"options": {
"create_users": true,
"update_users": true,
"deactivate_users": true,
"deprov_behavior": "DEACTIVATE"
},
"enabled": true
}
Response 200: the connection object.
Errors:
| Status | error | When |
|---|---|---|
| 422 | refused | SCIM base URL rejected: URL must use https: http://10.0.0.1/scim; SCIM base URL rejected: URL host cannot be resolved: expenses.acme.example |
Turn provisioning on or off
PUT /api/v1/apps/{slug}/scim/provisioning
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | no | true creates the connection if it is missing. false or left out deletes the connection with its mappings, scope and jobs. |
Response 204. Accounts already created in the application are left as they are.
Set the token
PUT /api/v1/apps/{slug}/scim/token
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | no | The bearer token Sovrain sends to the application. At most 8192 characters. Blank or left out: nothing changes. Any other value, even the stored token, marks the connection as not tested. |
Response 204. The token is stored encrypted and can never be read back.
Test the connection
POST /api/v1/apps/{slug}/scim/test
| Field | Type | Required | Notes |
|---|---|---|---|
mode | string | no | user runs the test with a temporary user. Any other value, or none, runs the connection test. |
base_url | string | no | Saved before the test |
token | string | no | Saved before the test |
The body is optional. What each test does: SCIM › Tests.
Response 200, also when the test fails:
{
"status": "ok",
"detail": "…"
}
status is ok, auth_failed, timeout or error. A passing test lifts a pause and unlocks provisioning.
Errors: 422 refused when no URL or no token is stored, for example
Set the SCIM base URL before testing the connection.
Replace the attribute mapping
PUT /api/v1/apps/{slug}/scim/mapping
PUT /api/v1/apps/{slug}/scim/mapping?dry_run=true
| Field | Type | Required | Notes |
|---|---|---|---|
username_source | string | yes | EMAIL, LOGIN, ID or EXTERNAL_ID, in upper case |
mappings | array | no | The complete list, each {source, path}. source is a built-in attribute or user_attributes.<name> for an attribute of the bank. Left out: every mapping is removed. At most 200. Path rules: SCIM › Attribute mapping. |
{
"username_source": "EMAIL",
"mappings": [
{ "source": "email", "path": "emails[type eq \"work\"].value" },
{ "source": "firstName", "path": "name.givenName" },
{ "source": "lastName", "path": "name.familyName" }
]
}
Response 200, the number of jobs queued (they wait 3 minutes before they run):
{ "queued": 12 }
With dry_run=true nothing is saved, and the response is the impact:
{
"user_creates": 0,
"user_updates": 12,
"user_deactivates": 0,
"user_deletes": 0,
"group_creates": 0,
"group_updates": 0,
"group_deletes": 0,
"skip_reasons": []
}
Errors: 422 refused, for example Unknown userName source 'email', or a path that breaks the rules.
Replace the scope
PUT /api/v1/apps/{slug}/scim/scope
PUT /api/v1/apps/{slug}/scim/scope?dry_run=true
| Field | Type | Required | Notes |
|---|---|---|---|
everyone | boolean | no | Default false. true: everyone in the organization is in scope. |
groups | array | no | Left out: none. At most 5000. Each {id, sync, sp_name}. |
groups[].id | string | yes | Group id |
groups[].sync | boolean | no | Default false: provision the members only. true: also create the group in the application. |
groups[].sp_name | string | no | The group’s name in the application, when sync is true. At most 255 characters. Default: the group’s name. |
users | array of user ids | no | Users in scope besides the groups. Left out: none. At most 5000. |
The whole scope is replaced. Invited users are never provisioned.
{
"everyone": false,
"groups": [ { "id": "SuT8oWQLVMPzwYQyhKjm32", "sync": true, "sp_name": "Engineering" } ],
"users": ["FomjVqEuLmL5CBPAfVwYK2"]
}
Response 200:
{ "queued": 3, "canceled": 0 }
canceled counts jobs of the old scope that were still waiting and are no longer needed. With dry_run=true the
response is the impact object shown above.
Errors: 422 refused for an unknown group or more than 5000 entries; 404 not_found for an unknown user.
Retry failed jobs
POST /api/v1/apps/{slug}/scim/jobs/retry-all
No body. Queues every failed and rejected job again.
Response 200:
{ "retried": 2 }
Reconcile now
POST /api/v1/apps/{slug}/scim/reconcile
No body. Runs a reconciliation with the application and waits for it. What it does: SCIM › Reconciliation.
Response 200:
{
"outcome": "not_operational",
"message": "Reconciliation skipped — provisioning is not active for this application."
}
outcome is done, not_operational or sp_unreadable. The drift found is not returned; it is shown on the
application’s Activity tab.