SCIM Provisioning
ANTS Platform exposes a SCIM 2.0 endpoint so your identity provider can add people to an organization, keep their names and roles up to date, push groups and their members, and remove people's access when they leave. Okta and Microsoft Entra ID work with their standard SCIM settings, including Entra's default attribute mappings.
SCIM manages organization membership, organization roles and groups. Groups set roles, including custom roles and project roles, through group role mapping. SCIM does not manage passwords; people provisioned this way sign in with SSO.
SCIM authenticates with an organization API key. Only the Owner role can create one, under Organization Settings → API Keys, and that tab needs the admin-api entitlement. See API Keys and Billing & Plans.
Authentication
Every SCIM request carries an organization API key in one of two forms:
| Form | Use it for |
|---|---|
Authorization: Basic base64(<public key>:<secret key>) | Okta app integrations set to Basic Auth, scripts, and any client that supports HTTP Basic. |
Authorization: Bearer <public key>:<secret key> | Clients that only send a bearer token, such as Microsoft Entra ID and Okta's HTTP Header mode. The token is the public key, a colon, then the secret key. The secret is checked exactly as with Basic. |
- A project API key is refused with
403. - A bearer token that is only the public key is refused.
- The
Bearer <public key>:<secret key>form works on the SCIM endpoints only. Other API routes refuse it.
The SCIM base URL is https://<your-host>/api/public/scim. Your identity provider must be able to reach it over HTTPS. A self-hosted deployment on a private network must expose that path to your identity provider (for Okta, to Okta's IP ranges) or use the identity provider's on-premises provisioning agent.
Connect your identity provider
Create an organization API key
Go to Organization Settings → API Keys and select Create API keys. Copy the public key (pk-...) and the secret key (sk-...). The secret key is shown only once. Add a note such as "Okta SCIM" so other administrators know what the key is for.
Use a dedicated key for SCIM. Once it has made a successful SCIM change, ANTS Platform marks it as used by SCIM provisioning, so it is never revoked automatically when the person who created it leaves. See API keys created by the person.
Configure provisioning in your identity provider
- Open the app integration you use for ANTS Platform. On the General tab, edit App Settings and set Provisioning to SCIM. A Provisioning tab appears.
- On Provisioning → Integration, set:
| Okta field | Value |
|---|---|
| SCIM connector base URL | https://<your-host>/api/public/scim |
| Unique identifier field for users | userName |
| Supported provisioning actions | Push New Users, Push Profile Updates and Push Groups |
| Authentication Mode | Basic Auth, with the public key as the username and the secret key as the password. Or HTTP Header, with <public key>:<secret key> as the token. |
- Select Test Connector Configuration, then save.
- On Provisioning → To App, enable Create Users, Update User Attributes and Deactivate Users.
- Make sure each user's Okta username is their email address. ANTS Platform uses
userNameas the email.
Test with a pilot user
Assign one pilot user in your identity provider and check that they appear under Organization Settings → Members. To use groups, push one pilot group (in Okta, Push Groups) and check that it is offered when you add a mapping under Organization Settings → Group role mapping.
Review the SCIM provisioning settings
Go to Organization Settings → Features → SCIM provisioning and decide how deprovisioning should treat keys. See SCIM provisioning settings.
Endpoints
All paths are relative to https://<your-host>/api/public/scim. Responses use Content-Type: application/scim+json. POST requests answer 201 with a Location header. There are no Bulk or Me endpoints.
| Method and path | What it does |
|---|---|
GET /ServiceProviderConfig | Capabilities: PATCH and filter supported (up to 100 results); bulk, sort, ETag and password change not supported. Advertises HTTP Basic and the bearer key pair. |
GET /Schemas | The User and Group schemas. |
GET /ResourceTypes | Two resource types, User and Group. |
GET /Users | Lists the organization's members. Supports filter=userName eq "<email>" (case-insensitive) or filter=externalId eq "<id>", startIndex (default 1) and count (default 100). Any other filter returns 400. |
POST /Users | Adds a user to the organization. |
GET /Users/{id} | Returns one user. Someone deactivated through SCIM is returned with "active": false. |
PUT /Users/{id} | Sets active, roles (only when sent), name and externalId. |
PATCH /Users/{id} | add, replace and remove operations. See Updating users. |
DELETE /Users/{id} | Deactivates the user and removes them from this organization's groups. Returns 204. |
GET /Groups | Lists the organization's groups. Supports filter on displayName, externalId or id with eq, startIndex, count (at most 100) and excludedAttributes=members. |
POST /Groups | Creates a group, with optional externalId and members. |
GET /Groups/{id} | Returns one group and its members. Supports excludedAttributes=members. |
PUT /Groups/{id} | Replaces the name, externalId and members. Returns 200. |
PATCH /Groups/{id} | Adds, removes or replaces members, and renames the group. Returns 204. |
DELETE /Groups/{id} | Deletes the group and the role mappings that use it. Returns 204. |
Errors use the SCIM error schema with detail, status (as a string, for example "409") and, where it applies, scimType such as invalidFilter, invalidValue, mutability or uniqueness.
A user ID that is out of your organization's reach returns 404, as does another organization's group.
Creating users
POST /Users reads these attributes:
| Attribute | Use |
|---|---|
userName | Required. The user's email address. Stored in lower case. |
name.givenName, name.familyName | Stored for this organization and returned in responses. |
name.formatted, displayName | The display name when a new account is created. |
externalId | Your identity provider's ID for the user. Can be used in filters. |
roles | Optional. The organization role. See Roles. |
Other attributes, such as password and emails, are ignored. When no account exists for the email address, one is created.
If the person is already a member of the organization, the request returns 409.
Existing accounts
When an account with that email already exists, SCIM adds it to your organization only when one of these is true:
- its email domain is a verified domain of your organization;
- your organization provisioned the person through SCIM before;
- the account does not belong to any organization yet, for example after a first SSO sign-in.
Otherwise the request returns 409, with no details about the account. The transitional setting Link existing accounts by email turns this check off. See SCIM provisioning settings.
Updating users
PATCH /Users/{id} accepts add, replace and remove operations, with a path or with a value object.
| Attribute | Handling |
|---|---|
active | true or false (also the strings "True" and "False" that Entra sends). false deactivates the user. |
name.givenName, name.familyName, externalId | Stored. remove clears them. |
roles, roles[primary eq "True"].value | Changes the organization role. remove leaves the role unchanged. |
displayName, name.formatted, emails, phoneNumbers, addresses, title, locale, timezone, the enterprise extension and other standard attributes | Accepted and ignored. The account's name and email belong to the person, not to one organization's directory. |
| Anything else | 400. |
Both of these deactivate a user:
PUT /Users/{id} with "active": false and DELETE /Users/{id} deactivate the user too. A PUT without active or roles, such as an Okta profile push, only updates the name and externalId.
Roles
roles is a list. Each entry is a plain string such as "AUDITOR" or a SCIM role object such as { "value": "AUDITOR", "primary": true }. With several entries, the one marked primary wins, otherwise the first.
A value is either a built-in role or the name or ID of a custom role in your organization. Built-in values are case sensitive:
| Value | Role |
|---|---|
OWNER | Owner |
DEPARTMENT_ADMIN | Department Admin |
SECURITY_COMPLIANCE_ADMIN | Security & Compliance |
ROI_ANALYST | Cost Analyst |
AUDITOR | Auditor |
MANAGER_VIEWER | Manager Viewer |
END_USER | End User |
NONE | None |
- Only an explicit
rolesvalue changes a role. APUTorPATCHwithoutrolesleaves the role as it is, so roles assigned in ANTS Platform survive profile pushes. - When a new member is created without
roles, they get None: no organization access until a role is granted. - A custom role needs the
rbac-custom-rolesentitlement. Without it, the request returns400. POSTandPATCHwith an unknown role return400. APUTwith no recognised role is treated as sending no role.- A role change that would leave the organization without an administrator is refused with
400. An administrator here is an Owner, or a member whose custom role has User & role management at Read & Write. - When a member's organization role is managed by a group role mapping,
rolesis ignored for them and the request still succeeds.
Groups
A SCIM group belongs to one organization. It has a displayName, an optional externalId and a list of members, each referencing a user by the id that /Users returned. Push users before the groups that contain them.
PATCH /Groups/{id} handles the shapes Okta and Entra send, applied in order:
| Operation | Effect |
|---|---|
replace with {"id": ..., "displayName": "New name"}, or replace with path displayName | Renames the group. |
add with path members | Adds members. |
remove with path members[value eq "<user id>"] | Removes one member (Okta). |
remove with path members and a list of members | Removes those members (Entra). An empty list changes nothing. |
remove with path members and no value | Removes every member. |
replace with path members | Replaces the member list. |
replace with path externalId | Sets the external ID. |
Rules:
- Group names are unique in the organization, ignoring case. A clash, including on rename, returns
409. - Members must be members of the organization or people it provisioned through SCIM. Other IDs are skipped, never an error.
- A group on its own grants nothing. Map it to a role under group role mapping. Every membership change pushed through SCIM recomputes the roles of the members it touches straight away.
- Deleting a group removes the mappings that use it and recomputes its former members' roles.
Deactivating users
PATCH or PUT with active set to false, and DELETE, deactivate a user in your organization. In one transaction, ANTS Platform:
- removes the organization membership, including any custom role, and every project membership in that organization;
- ends the person's open console sessions if this was their last organization: their next request is refused and they are signed out. If they still belong to another organization, they stay signed in there but lose access to yours;
- blocks the Budget AI keys tied to the person in that organization: keys they claimed, and keys they created for themselves. Requests with those keys are refused within seconds;
- revokes Budget AI claim links that are still waiting for the person, and unclaimed links they issued;
- finds the ANTS Platform API keys they created in the organization. See API keys created by the person;
- writes audit records, including a
scim.deprovisionentry with the counts of what was removed, blocked and flagged.
The user account itself is kept, so the person keeps access to any other organization they belong to. DELETE also removes them from your organization's SCIM groups.
Deactivating the organization's last administrator (the last Owner, or the last member whose custom role can manage members) is refused with 400. Your identity provider shows a failed provisioning task. Grant another member the Owner role first.
A retried deactivation changes nothing, so it never re-blocks a key an administrator has unblocked since.
Budget AI keys for agents and org units
Keys the person created for an agent or an org unit keep working by default, so offboarding someone does not stop production agents. Members who administer Budget AI keys (Owner, Department Admin and Security & Compliance among the built-in roles) get an in-app notification, Keys of a deprovisioned person, and an email asking them to rotate those keys. An audit entry lists them. The notification and email are not sent when the organization has turned off in-app notifications.
To block those keys too, turn on Block agent keys of deprovisioned people. See SCIM provisioning settings.
Rotating a key keeps its owner. A developer's key that an administrator rotated still belongs to the developer, so it is blocked when the developer leaves, not when the administrator leaves.
API keys created by the person
ANTS Platform records who created each organization and project API key. On deactivation it finds the keys the person created in your organization: organization keys, and project keys in its projects.
- By default the keys keep working, because revoking an ingestion key stops data flowing. They are listed in the rotation notification and email, which then also go to members who manage organization API keys, and in an audit entry (
scim.deprovision.apiKeysNeedRotation) with their public keys, scope, project and note. Secrets are never recorded. - With Revoke API keys created by a deprovisioned person on, the keys are deleted and stop authenticating on the next request. Each deletion writes an audit entry with the reason
deprovisioned. - Some keys are never revoked automatically, even with the setting on. They are flagged for rotation instead, and the notification says why each one was kept:
- Discover AI keys;
- AI agent connector, MS Graph connector and Copilot Studio connector keys;
- keys that have made a successful SCIM change or a successful governance API request;
- the key that sent the deactivation request.
- Keys with no recorded creator are not touched. They show Unknown in the Created by column. See API Keys.
Reactivating users
PATCH or PUT with "active": true, or POST /Users again, adds the membership back with the role in roles, or None when no role is sent. If the person is still in mapped SCIM groups, their group role mapping applies again.
Keys stay blocked. Reactivation never unblocks the Budget AI keys that deactivation blocked. The scim.reactivate audit entry lists them, so an administrator can review them and unblock the ones that should work again. API keys that were revoked are gone; create new ones.
SCIM provisioning settings
Go to Organization Settings → Features → SCIM provisioning. Changing these settings needs tenant security feature administration (Owner and Security & Compliance among the built-in roles). All three are off by default, and every change is recorded in Audit Logs.
| Setting | When on | Step-up verification |
|---|---|---|
| Block agent keys of deprovisioned people | Budget AI keys a deprovisioned person created for an agent or an org unit are blocked too. This can stop agents that use them. | When turning it off |
| Revoke API keys created by a deprovisioned person | The ANTS Platform API keys a deprovisioned person created in this organization are deleted at once, except the kinds that are never revoked automatically. While it is off, the setting shows how many existing keys it would make revocable. | When turning it on and when turning it off |
| Link existing accounts by email | POST /Users adds any existing account with the same email to the organization, including accounts that belong to other organizations. Transitional: verify your email domains instead and leave this off. | When turning it on |
Step-up verification applies when it is enabled on the deployment.
Audit records
Every SCIM change is recorded in Audit Logs. The Actor is the organization API key that made the request.
| Resource | Actions |
|---|---|
orgMembership | scim.create, scim.roleUpdate, scim.deprovision, scim.reactivate |
scimUser | scim.profileUpdate, scim.groupMembershipsRemoved |
scimGroup | create, update, replace, delete |
gatewayKey | block with reason deprovisioned, and scim.deprovision.keysNeedRotation |
apiKey | delete with reason deprovisioned when revocation is on, and scim.deprovision.apiKeysNeedRotation |
Role changes caused by a group change are recorded as groupRoleMapping.roleUpdate. See Group Role Mapping.
Okta access reconciliation (self-hosted)
Self-hosted deployments that use Okta can also run a scheduled reconciliation job. It compares organization members with the active members of chosen Okta groups and removes people who are no longer in them. It is configured with environment variables on the deployment, not in the product, and is off by default.
| Variable | Default | Meaning |
|---|---|---|
AUTH_OKTA_RECONCILIATION_ENABLED | false | Turns the job on. |
AUTH_OKTA_API_TOKEN, AUTH_OKTA_ISSUER | none | Okta API token and Okta tenant. |
AUTH_OKTA_RECONCILIATION_GROUPS | none | Okta group names or patterns that define who should have access. |
AUTH_OKTA_RECONCILIATION_ORG_IDS | none | Organizations to reconcile. |
AUTH_DOMAINS_WITH_SSO_ENFORCEMENT | none | Only members with these email domains are checked. |
AUTH_OKTA_RECONCILIATION_MODE | report | report records drift only. enforce removes access. |
AUTH_OKTA_RECONCILIATION_MAX_REMOVALS | 25 | The whole run stops if it would remove more people than this. |
AUTH_OKTA_RECONCILIATION_MAX_REMOVAL_PERCENT | 20 | An organization is skipped if it would lose a larger share of members. |
AUTH_OKTA_RECONCILIATION_CRON | 30 20 * * * | Schedule, in UTC. |
How it behaves:
- Suspended and deprovisioned Okta users count as gone. Instance administrators are never removed.
- The run stops without changes if Okta returns an error, a partial list, no matching groups or no members.
- An organization is skipped if the removals would leave it without anyone who can manage members.
- In
enforcemode, a removal is the same deprovisioning as a SCIM deactivation: membership and project memberships removed, console sessions ended when it was the person's last organization, Budget AI keys blocked or flagged, claim links revoked, and API keys flagged or revoked, following the SCIM provisioning settings. The rotation notification is sent the same way. - It never adds members or changes roles.
- Every run writes to Audit Logs:
okta_reconciliation.drift_detectedin report mode,membership.deprovisioned.okta_reconciliationfor each removal,okta_reconciliation.keysNeedRotationandokta_reconciliation.apiKeysNeedRotationfor flagged keys, andokta_reconciliation.abortedwhen a safety check stops the run.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
401 on every request | The key is wrong, deleted or expired. Organization keys expire 6 months after creation. Create a new key and update the identity provider. |
403 "Organization-scoped API key required" | A project key was used. Use an organization key. |
409 on POST /Users | The person is already a member, or their account belongs to another organization and their email domain is not verified for yours. Verify the domain, or use Link existing accounts by email while you do. |
400 with mutability on deactivation | The person is the last administrator. Grant another member the Owner role first. |
400 with invalidFilter | Only userName eq and externalId eq (users), and displayName eq, externalId eq and id eq (groups), are supported. |
A role sent in roles is not applied | The member's organization role is managed by a group role mapping. Change the mapping or the person's groups instead. |
| A deactivated person's Budget AI key still works | The key is for an agent or an org unit, or someone else claimed it. Rotate it, or turn on Block agent keys of deprovisioned people. |
| A reactivated person cannot use their Budget AI key | Reactivation leaves keys blocked. An administrator unblocks the key in Budget AI. |
Next steps
- Group Role Mapping: give SCIM groups and sign-in groups a role.
- Single Sign-On (SSO): sign-in for provisioned users.
- API Keys: organization keys and who created each key.
- Members & Roles: what each role can do.