Docs/Administration/Scim Provisioning

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:

FormUse 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

  1. 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.
  2. On Provisioning → Integration, set:
Okta fieldValue
SCIM connector base URLhttps://<your-host>/api/public/scim
Unique identifier field for usersuserName
Supported provisioning actionsPush New Users, Push Profile Updates and Push Groups
Authentication ModeBasic 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.
  1. Select Test Connector Configuration, then save.
  2. On Provisioning → To App, enable Create Users, Update User Attributes and Deactivate Users.
  3. Make sure each user's Okta username is their email address. ANTS Platform uses userName as 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 pathWhat it does
GET /ServiceProviderConfigCapabilities: 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 /SchemasThe User and Group schemas.
GET /ResourceTypesTwo resource types, User and Group.
GET /UsersLists 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 /UsersAdds 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 /GroupsLists the organization's groups. Supports filter on displayName, externalId or id with eq, startIndex, count (at most 100) and excludedAttributes=members.
POST /GroupsCreates 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:

AttributeUse
userNameRequired. The user's email address. Stored in lower case.
name.givenName, name.familyNameStored for this organization and returned in responses.
name.formatted, displayNameThe display name when a new account is created.
externalIdYour identity provider's ID for the user. Can be used in filters.
rolesOptional. 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.

json
{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "jane.doe@example.com", "name": { "givenName": "Jane", "familyName": "Doe" }, "roles": [{ "value": "END_USER", "primary": true }] }

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.

AttributeHandling
activetrue or false (also the strings "True" and "False" that Entra sends). false deactivates the user.
name.givenName, name.familyName, externalIdStored. remove clears them.
roles, roles[primary eq "True"].valueChanges the organization role. remove leaves the role unchanged.
displayName, name.formatted, emails, phoneNumbers, addresses, title, locale, timezone, the enterprise extension and other standard attributesAccepted and ignored. The account's name and email belong to the person, not to one organization's directory.
Anything else400.

Both of these deactivate a user:

json
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace", "value": { "active": false } }] }
json
{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace", "path": "active", "value": false }] }

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:

ValueRole
OWNEROwner
DEPARTMENT_ADMINDepartment Admin
SECURITY_COMPLIANCE_ADMINSecurity & Compliance
ROI_ANALYSTCost Analyst
AUDITORAuditor
MANAGER_VIEWERManager Viewer
END_USEREnd User
NONENone
  • Only an explicit roles value changes a role. A PUT or PATCH without roles leaves 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-roles entitlement. Without it, the request returns 400.
  • POST and PATCH with an unknown role return 400. A PUT with 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, roles is 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.

json
{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "AI-Security", "members": [{ "value": "<user id>" }] }

PATCH /Groups/{id} handles the shapes Okta and Entra send, applied in order:

OperationEffect
replace with {"id": ..., "displayName": "New name"}, or replace with path displayNameRenames the group.
add with path membersAdds members.
remove with path members[value eq "<user id>"]Removes one member (Okta).
remove with path members and a list of membersRemoves those members (Entra). An empty list changes nothing.
remove with path members and no valueRemoves every member.
replace with path membersReplaces the member list.
replace with path externalIdSets 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.deprovision entry 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.

SettingWhen onStep-up verification
Block agent keys of deprovisioned peopleBudget 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 personThe 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 emailPOST /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.

ResourceActions
orgMembershipscim.create, scim.roleUpdate, scim.deprovision, scim.reactivate
scimUserscim.profileUpdate, scim.groupMembershipsRemoved
scimGroupcreate, update, replace, delete
gatewayKeyblock with reason deprovisioned, and scim.deprovision.keysNeedRotation
apiKeydelete 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.

VariableDefaultMeaning
AUTH_OKTA_RECONCILIATION_ENABLEDfalseTurns the job on.
AUTH_OKTA_API_TOKEN, AUTH_OKTA_ISSUERnoneOkta API token and Okta tenant.
AUTH_OKTA_RECONCILIATION_GROUPSnoneOkta group names or patterns that define who should have access.
AUTH_OKTA_RECONCILIATION_ORG_IDSnoneOrganizations to reconcile.
AUTH_DOMAINS_WITH_SSO_ENFORCEMENTnoneOnly members with these email domains are checked.
AUTH_OKTA_RECONCILIATION_MODEreportreport records drift only. enforce removes access.
AUTH_OKTA_RECONCILIATION_MAX_REMOVALS25The whole run stops if it would remove more people than this.
AUTH_OKTA_RECONCILIATION_MAX_REMOVAL_PERCENT20An organization is skipped if it would lose a larger share of members.
AUTH_OKTA_RECONCILIATION_CRON30 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 enforce mode, 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_detected in report mode, membership.deprovisioned.okta_reconciliation for each removal, okta_reconciliation.keysNeedRotation and okta_reconciliation.apiKeysNeedRotation for flagged keys, and okta_reconciliation.aborted when a safety check stops the run.

Troubleshooting

SymptomCause and fix
401 on every requestThe 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 /UsersThe 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 deactivationThe person is the last administrator. Grant another member the Owner role first.
400 with invalidFilterOnly userName eq and externalId eq (users), and displayName eq, externalId eq and id eq (groups), are supported.
A role sent in roles is not appliedThe 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 worksThe 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 keyReactivation leaves keys blocked. An administrator unblocks the key in Budget AI.

Next steps

© 2026 ANTS Platform, Inc.Docs v1.0 · Last updated June 2026