Provision users and groups with SCIM
AtmanID runs a SCIM 2.0 server. Your identity provider (IdP), for example Okta or Microsoft Entra ID, calls it to create people in AtmanID, keep their name and email current, suspend them when they are disabled, remove them when they are deleted, and push groups. AtmanID does not call your IdP; every change on this page starts with a request from it.
In the examples, $ATMANID_BASE_URL is the address of your AtmanID tenant, and $SCIM_TOKEN is a token you create below.
Before you start
- You need a role that can configure SCIM: identity admin, tenant owner or super admin.
- Inbound provisioning must be on. It is on unless someone has turned it off with the Inbound provisioning switch on the SCIM Provisioning page. While it is off, every SCIM request with a valid token is answered
403and nothing is written. - Read what is not supported yet before you connect a production IdP.
The base URL
Point your IdP at:
$ATMANID_BASE_URL/api/scim/v2| Resource | Path | Methods |
|---|---|---|
| Users | /Users |
GET, POST |
| One user | /Users/{id} |
GET, PUT, PATCH, DELETE |
| Groups | /Groups |
GET, POST |
| One group | /Groups/{id} |
GET, PUT, PATCH, DELETE |
| Service provider config | /ServiceProviderConfig |
GET, no token needed |
| Schemas | /Schemas |
GET, no token needed |
| Resource types | /ResourceTypes |
GET, no token needed |
The SCIM Provisioning page (Inbound tab) shows the same base URL for your tenant with a copy button. A separate health check, $ATMANID_BASE_URL/api/scim/health, needs no token and always answers 200: status is operational when AtmanID can reach its database and degraded when it cannot.
Create a token
- Open SCIM Provisioning and stay on the Inbound tab.
- Under SCIM Bearer Tokens, type a name that says which IdP will use it, for example
Okta production, and select Generate Token. - Copy the token straight away. It is shown once. AtmanID keeps only a SHA-256 hash of it and shows its first eight characters in the list so you can tell tokens apart.
A token is 64 hexadecimal characters. It does not expire. It belongs to the tenant it was created in: AtmanID works out which tenant a SCIM request is for from the token alone, so one IdP connection can only ever write to one tenant. Revoke a token from the same list; every request is checked against the stored hashes, so the next request with a revoked token gets 401. Creating and revoking a token are audited as SCIM_TOKEN_CREATED and SCIM_TOKEN_REVOKED.
Send the token on every request:
curl -s "$ATMANID_BASE_URL/api/scim/v2/Users?count=5" \ -H "Authorization: Bearer $SCIM_TOKEN"A missing, unknown or revoked token gets 401 with the detail Unauthorized — valid Bearer token required.
Users
Attributes
| SCIM attribute | Stored as | Notes |
|---|---|---|
userName |
Also returned as emails[0].value and externalId. |
|
emails[0].value |
Used only when userName is absent. |
|
name.givenName, name.familyName |
first and last name | name.formatted is returned, not stored. |
title |
job title | |
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User department |
department | Subject to the department source setting on create. |
active |
status | true or false, or the strings "True"/"False" in any case. Anything else is refused with 400. |
Other attributes in the body are accepted and ignored. AtmanID returns its own id (a UUID) for each user; use it in /Users/{id}.
Create a user
curl -s -X POST "$ATMANID_BASE_URL/api/scim/v2/Users" \ -H "Authorization: Bearer $SCIM_TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "ada@example.com", "name": { "givenName": "Ada", "familyName": "Lovelace" }, "title": "Analyst", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": "Finance" }, "active": true }'userName or an email is required. A new person is created ACTIVE, or SUSPENDED and held by the IdP when the body says "active": false, so a later active: true makes them active. A second create with an email that already exists in the tenant gets 409.
Before anything is written, the create is checked against the Provisioning Rules card on the SCIM Provisioning page, in this order:
- Auto-Provision off: every create is refused. Updates to people who already exist still apply.
- Allowed Email Domains set: the email’s domain must be in the list (case-insensitive).
- Excluded Departments set: a person whose department matches an entry is refused (case-insensitive).
A refused create gets 403 with the reason in detail, for example Email domain 'contractor.io' is not in the provisioning scope (allowed: example.com), and is audited as SCIM_USER_PROVISION_BLOCKED with the same reason. It is never dropped silently.
The same card sets what a created person gets:
- Default Platform Role: assigned on create. A stored value of
super_admin, or anything that is not a platform role, is replaced withend_user. If the role cannot be assigned, the person is still created and the failure is logged. - Department Source: with SCIM (the default) the department from the IdP is stored; with manual or HR, the configured default department is stored instead.
- Require MFA at First Login: when on, the created person is required to use MFA whatever their role’s MFA policy says.
A successful create is audited as SCIM_USER_PROVISIONED, with the applied default role, MFA requirement and department source.
Read a user or the list
GET /Users/{id} returns 404 for an unknown id and for a person who has been deprovisioned.
GET /Users returns the tenant’s users, oldest first, a page at a time. startIndex is 1-based (default 1) and count is the page size (default 100, at most 200; 0 returns only the total). totalResults is the number of users that match, across all pages. Deprovisioned people are left out of the list, as they are from GET /Users/{id}.
IdPs look a person up before creating them, so GET /Users takes a filter with one equality test:
| Filter | Matches |
|---|---|
userName eq "ada@example.com" |
The person with that email, in any letter case. |
emails[value eq "…"], emails[type eq "work" and value eq "…"], emails.value eq "…", emails eq "…" |
The same. |
externalId eq "…" |
The same, because AtmanID returns the email as externalId. An externalId your IdP sent is not stored, so filtering by your IdP’s own identifier finds nobody. |
id eq "…" |
The person with that AtmanID id. |
Attribute names and eq can be in any case, and an attribute can carry the core schema prefix (urn:ietf:params:scim:schemas:core:2.0:User:userName). A filter that matches nobody returns totalResults: 0 and no users. Any other filter, such as co, sw, pr, or, and outside emails[...], or another attribute, is refused with 400 and scimType: invalidFilter; it is never ignored.
curl -s -G "$ATMANID_BASE_URL/api/scim/v2/Users" \ -H "Authorization: Bearer $SCIM_TOKEN" \ --data-urlencode 'filter=userName eq "ada@example.com"'Update a user
PUT replaces the email, first name, last name, title and department with the values in the body. An attribute left out is stored as empty. When active is present it is applied as described in suspension and removal; when it is absent the status does not change. If the department or title changes for a person who is active afterwards, the change is audited (MOVER_AUTO_DETECTED) and passed to lifecycle automation as a mover, by the mode set for that kind of person. The department source setting is not applied to PUT.
PATCH applies these operations:
| Operation | Effect |
|---|---|
replace, path active |
Suspends or restores, as below. |
replace, path userName or emails[type eq "work"].value |
Changes the email. |
replace, no path, value object with active |
Suspends or restores. Key names match in any case. |
replace, no path, value object with givenName / name.givenName, familyName / name.familyName |
Changes the first or last name. |
replace or add, path title or urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department |
Changes the title or department. remove with the same path clears it. |
replace or add, no path, value object with title, department or the enterprise extension object |
Changes the title or department. |
A title or department must be a string of at most 200 characters, or null to clear it; anything else is refused with 400 before anything changes. The department follows the department source setting: unless it is SCIM, a PATCH does not change the department (the title still changes). When several operations set the same attribute, the last one applies. A change of department or title for a person who is active afterwards is passed on as a mover, as for PUT. Any other operation, such as remove of another attribute or a replace with a path such as name.givenName, is accepted and has no effect. Every PATCH is audited, as SCIM_USER_UPDATED unless it suspended or deprovisioned the person.
curl -s -X PATCH "$ATMANID_BASE_URL/api/scim/v2/Users/$USER_ID" \ -H "Authorization: Bearer $SCIM_TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace", "path": "active", "value": false }] }'Changing the email of an administrator
The email is the account’s sign-in name and where its password-reset mail goes. A SCIM token has no person behind it, so AtmanID treats it as holding the authority of an identity admin, the lowest role that can create one. When a PUT or PATCH would change the email of an account that holds permissions beyond that (a tenant owner, a super admin, or a custom admin role with more), AtmanID checks it before anything is written:
- By default (warn mode) the change is made and audited as
SCIM_EMAIL_CHANGE_WOULD_DENY, with the permissions the account holds beyond the ceiling. - When a platform operator turns on enforcement, the request is refused with
403and audited asSCIM_EMAIL_CHANGE_REFUSED. Nothing in that request is applied. The detail tells your IdP admin to change that email in AtmanID as an administrator who holds those permissions.
Suspension and removal
active: false suspends; it is not a leaver. DELETE is the leaver.
| Request | Person’s status before | What happens |
|---|---|---|
active: false |
ACTIVE |
SUSPENDED, held by the IdP. Their AtmanID sessions end at once. Entitlements, roles and requests are kept. Audited USER_SUSPENDED. |
active: false |
ON_LEAVE, LOCKED or already SUSPENDED |
The status stays. AtmanID records that the IdP disabled them, so lifting the status later lands in SUSPENDED. Audited USER_IDP_DISABLED_MARKED. |
active: false |
PRE_HIRE |
The hire is rescinded: DEPROVISIONED, with the leaver revocation and revocation tickets. |
active: true |
suspended by the IdP | Back to ACTIVE under the same rules as an admin reactivation, so an external whose end date has passed stays suspended. Audited USER_SCIM_REACTIVATED. |
active: true |
deprovisioned because of the IdP (its suspension window ran out, or a rescinded pre-hire) | A rehire: ACTIVE, with none of their previous access restored. Audited SCIM_USER_REHIRED. Deferred (SCIM_REACTIVATE_DEFERRED) while leaver work for them is still open; the IdP’s next push retries. |
active: true |
left for any other reason (an admin, HR, an emergency termination, a SCIM DELETE), or EXPIRED |
Not reactivated. The response is 200 with active: false, audited SCIM_REACTIVATE_REFUSED_DEPARTED at most once a day per person. Bringing them back is an admin’s reinstatement. |
DELETE |
anyone | DEPROVISIONED. The record is kept for the audit trail. Returns 204. |
While a person is not ACTIVE, API keys, MCP tokens and agent tokens they own are refused when used. They are not revoked, so restoring the person makes them work again.
A person the IdP suspends does not stay suspended forever. A daily job runs the full leaver for anyone the IdP disabled more than 30 days earlier. The window is a per-tenant setting, but there is no page or API to change it yet.
DELETE is the immediate leaver. In one transaction AtmanID sets the person to DEPROVISIONED and revokes their AtmanID authority: platform, custom admin and RBAC roles, unused MFA backup codes, and open access requests. API keys they created are counted and logged by default and revoked only when the platform’s leaver-revokes-API-keys setting is on. Then, for a person who had not already left, AtmanID opens a revocation ticket for every active account they hold in a connected application, with a termination priority and a four-hour SLA, for the revocation queue. The delete is audited as SCIM_USER_DELETED.
Groups
A SCIM group is stored as an AtmanID group with members. Supported attributes are displayName, externalId and members[].value. A member’s value can be the AtmanID user id or the person’s email; values that match nobody in the tenant are skipped.
| Request | Effect | Audit event |
|---|---|---|
POST /Groups |
Creates the group. A displayName that already exists (case-insensitive) gets 409. Each member found gets the membership and an approved access request recording the group. |
SCIM_GROUP_CREATED |
GET /Groups |
Lists groups with their members. Supports startIndex, count (at most 200) and the filter displayName eq "…". |
|
PUT /Groups/{id} |
Replaces the name, externalId and the whole member list. |
SCIM_GROUP_UPDATED |
PATCH /Groups/{id} |
add with path members adds members. remove with members[value eq "…"] removes one; with path members and a value list removes those; with path members and no value removes everyone. replace with a displayName in the value renames. Any other remove is refused with 400 before anything changes. |
SCIM_GROUP_UPDATED |
DELETE /Groups/{id} |
Deletes the group and its memberships. Returns 204. |
SCIM_GROUP_DELETED |
A person who has left is checked before they are added to a group on create, and is not added when the tenant enforces that check.
Discovery endpoints
/ServiceProviderConfig, /Schemas and /ResourceTypes need no token. They declare: PATCH supported; filtering supported with at most 200 results a page; bulk, sort, ETags and password change not supported; authentication with the per-tenant bearer token described above. /Schemas lists the core User schema, the enterprise extension and the core Group schema; /ResourceTypes lists User and Group.
Errors and limits
Errors use the SCIM error schema:
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "detail": "Resource not found", "status": "404"}| Status | When |
|---|---|
400 |
The body is not JSON, fails validation (detail names the field), a group remove this server cannot apply, or a user filter this server does not support (scimType: invalidFilter). |
401 |
No bearer token, or the token is unknown or revoked. |
403 |
Inbound provisioning is off, a create is outside the provisioning rules, or an administrator’s email change is refused under enforcement. |
404 |
The user or group does not exist in your tenant. |
409 |
The email (create) or group name (create) already exists. A deprovisioned person still holds their email, so creating them again gets 409 even though the list no longer shows them. |
429 |
Rate limited. Wait for the number of seconds in Retry-After. |
500, 503 |
A failure on AtmanID’s side. The user list and single-user read answer 503 rather than a partial or empty result. |
Writes to users and every groups request are limited to 60 requests a minute per client IP address for each path. The user reads are not rate limited.
Set up Okta
Okta labels vary between its app integration wizard versions; look for these fields.
- Create a SCIM app integration (or add SCIM provisioning to your existing AtmanID app) and open its provisioning settings.
- SCIM connector base URL:
$ATMANID_BASE_URL/api/scim/v2. - Unique identifier field for users:
userName. Map it to the person’s email, because AtmanID storesuserNameas the email. - Authentication mode: HTTP Header. Paste the token as the bearer token in Authorization.
- Choose the provisioning actions you want: push new users, push profile updates and push groups. Okta commonly sends profile updates as
PUT, which AtmanID applies to every attribute in the table above. - Test the connection, then assign one test person and confirm they appear in AtmanID with an audit event
SCIM_USER_PROVISIONED.
Set up Microsoft Entra ID
- In your enterprise application, open Provisioning and set the provisioning mode to Automatic.
- Under Admin Credentials, set Tenant URL to
$ATMANID_BASE_URL/api/scim/v2and Secret Token to the token. - Select Test Connection, then save.
- Review the attribute mappings. Keep
userNamemapped to the person’s email (oftenuserPrincipalNameormail), keep it as the matching attribute, and keepactivemapped. Entra ID matches people withGET /Users?filter=userName eq "…", which AtmanID answers exactly. Entra ID sends updates asPATCHwith apathfor each attribute; of those, AtmanID applies onlyactiveand the email paths (see Update). - Assign one test person, start provisioning, and check the provisioning log in Entra ID and the audit trail in AtmanID.
Entra ID sends active as the string "False"; AtmanID accepts that.
What is not supported yet
These are gaps in the current server, stated so you can plan around them.
- User filters are equality only, on the attributes listed in Read a user or the list. Other filters are refused with
400. GET /Groupsunderstands onlydisplayName eq "…". Any other group filter is ignored and every group is returned, so match groups by display name.- Re-creating a deprovisioned person gets
409. Their email stays reserved by the deprovisioned record. To bring someone back, an admin reinstates them in AtmanID. PATCHon a user ignores most attributes, as listed in Update. UsePUT, or map changes to the attributesPATCHapplies./Schemaslists an enterprisemanagerattribute that AtmanID does not store.- The Send Welcome Email setting on the Provisioning Rules card is saved but not used by SCIM creates.
- Deleting a group removes the memberships only. It does not open revocation tickets or revoke the access requests the group created.
- The suspension window (30 days by default) cannot be changed from the app.
- No bulk operations, sorting, ETags or password changes.
© AtmanID · Privacy