Skip to content

SCIM provisioning

Editions: Cloud, Enterprise. SCIM ships with the Preloop Enterprise enterprise_sso plugin.

SCIM 2.0 lets your identity provider create members, keep their profile and team membership current, and remove access when someone leaves. Removal runs the same offboarding as Removing a member: the membership is deactivated, its sessions and personal API keys are revoked, and account-owned automation keeps working. The person's memberships in other accounts are not touched.

Before you start

  • An enabled OIDC or SAML connection under Settings → Account → Single sign-on. Each SCIM token provisions exactly one connection.
  • For group sync, a group mapping on that connection whose IdP group name matches the SCIM group's display name and points at an existing team. SCIM never creates teams or roles.

Create a token

  1. Open Settings → Account → Single sign-on and go to SCIM tokens.
  2. Enter a token name and choose the Connection the token provisions for. With one connection it is preselected; with more than one you must choose. The form stays disabled until the account has an OIDC or SAML connection.
  3. Select Create SCIM token. Copy the token now: it is shown once, names its connection, and is stored only as a hash.
  4. The token list shows each token's connection. Revoke takes effect on the next request.

The API equivalent is POST /api/v1/accounts/{account_id}/sso/scim-tokens with body {"name": "...", "connection_id": "<connection id>"} (list and revoke on the same path).

Tokens created before connection binding was introduced have no connection and cannot provision. The console marks them Replace: create a new token bound to a connection, put it in your identity provider, then revoke the old one. A token whose connection was removed is marked the same way, and a token bound to a disabled connection is marked Connection disabled and cannot provision until that connection is enabled.

Connect your identity provider

Setting Value
SCIM base URL https://<your Preloop host>/scim/v2
Authentication HTTP header, bearer token
Unique identifier userName (an email address)
Supported resources Users, Groups

Each token is limited to 120 requests per minute. Further requests get 429 with Retry-After: 60.

What each operation does

IdP action Preloop result
Create user Adds a membership without a password or sign-in method. The person signs in through the bound connection, which verifies their email on first login. An existing member with the same email in this account is linked instead. An email that belongs to someone outside the account is refused with 409.
Update user Updates the provisioning profile for this connection only. The person's name and email in other accounts do not change.
active: false or delete Offboards the membership (sessions and personal keys revoked). Account owners are refused with 400; hand over ownership first.
active: true Re-enables the membership. Revoked keys and sessions stay revoked.
Push group / members Adds or removes the mapped team for those members. Team memberships added by hand or by OIDC/SAML group claims are kept.

Every request, including failures, is written to the audit log with the token prefix as the actor. The token itself is never logged.

Supported protocol

  • Discovery: ServiceProviderConfig, ResourceTypes, Schemas.
  • Filters: userName eq "..." on Users, displayName eq "..." on Groups, and members[value eq "..."] in PATCH paths. Other filters, sorting and unsupported query parameters return 400 invalidFilter or invalidValue rather than a broader result.
  • PATCH: add, replace and remove in any letter case, with or without a path; name.givenName-style and emails[type eq "work"].value paths; "True"/"False" strings for active.
  • Not supported: bulk, ETags, password changes. A password attribute is refused.
  • Common attributes such as locale, title, phoneNumbers and the enterprise user extension are accepted and not stored.
  • A request that fails validation changes nothing: a PATCH with one bad operation rolls back the whole request.

Okta

  1. In the Preloop app integration, enable SCIM provisioning and set the base URL above, unique identifier userName and authentication HTTP Header with the token.
  2. Under To App, enable Create Users, Update User Attributes and Deactivate Users. Leave Sync Password off; Preloop refuses passwords.
  3. Use Push Groups for groups that have a matching team mapping in Preloop.

Microsoft Entra ID

  1. In the enterprise application, set Provisioning Mode to Automatic, Tenant URL to the base URL and Secret Token to the token, then Test Connection.
  2. Map userPrincipalName or mail to userName. Remove attribute mappings Preloop does not use if Entra reports them as errors.
  3. Assign the groups whose display names match your team mappings.

Real-world compatibility with each IdP's current client has not yet been exercised against a production tenant; report anything that fails with the SCIM error body from your IdP's provisioning log.