Skip to content

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 403 and 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

  1. Open SCIM Provisioning and stay on the Inbound tab.
  2. Under SCIM Bearer Tokens, type a name that says which IdP will use it, for example Okta production, and select Generate Token.
  3. 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:

Terminal window
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 email Also returned as emails[0].value and externalId.
emails[0].value email 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

Terminal window
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:

  1. Auto-Provision off: every create is refused. Updates to people who already exist still apply.
  2. Allowed Email Domains set: the email’s domain must be in the list (case-insensitive).
  3. 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 with end_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.

Terminal window
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.

Terminal window
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 403 and audited as SCIM_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.

  1. Create a SCIM app integration (or add SCIM provisioning to your existing AtmanID app) and open its provisioning settings.
  2. SCIM connector base URL: $ATMANID_BASE_URL/api/scim/v2.
  3. Unique identifier field for users: userName. Map it to the person’s email, because AtmanID stores userName as the email.
  4. Authentication mode: HTTP Header. Paste the token as the bearer token in Authorization.
  5. 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.
  6. 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

  1. In your enterprise application, open Provisioning and set the provisioning mode to Automatic.
  2. Under Admin Credentials, set Tenant URL to $ATMANID_BASE_URL/api/scim/v2 and Secret Token to the token.
  3. Select Test Connection, then save.
  4. Review the attribute mappings. Keep userName mapped to the person’s email (often userPrincipalName or mail), keep it as the matching attribute, and keep active mapped. Entra ID matches people with GET /Users?filter=userName eq "…", which AtmanID answers exactly. Entra ID sends updates as PATCH with a path for each attribute; of those, AtmanID applies only active and the email paths (see Update).
  5. 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 /Groups understands only displayName 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.
  • PATCH on a user ignores most attributes, as listed in Update. Use PUT, or map changes to the attributes PATCH applies.
  • /Schemas lists an enterprise manager attribute 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