SCIM Provisioning

Sapling Enterprise teams can connect their identity provider (IdP) to Sapling over SCIM 2.0 to deprovision users automatically when they leave or lose access in the directory. SCIM works together with single sign-on (SSO): SSO signs users in, and SCIM controls whether they hold a seat on your Sapling team.

SCIM is available on the Enterprise plan. Contact team@sapling.ai to enable it. Sapling issues one SCIM token per organization.

Connection details

Setting	Value
SCIM version	SCIM 2.0 (Users and Groups)
Base URL	https://api.sapling.ai/scim/v2 (no trailing slash)
Authentication	Bearer token in the Authorization header (Authorization: Bearer <token>)
Unique identifier	userName (the user's email address)
Content type	application/scim+json or application/json

Tokens do not expire. Sapling rotates a token on request: we issue a new token, you update it in your IdP, and the old token is revoked. We recommend rotating at least annually and whenever an administrator with access to the token leaves.

Every SCIM request is recorded in an audit log for your organization.

How provisioning works

A Sapling account is created just-in-time the first time a user signs in with SSO, and users from your verified email domain are added to your Sapling team automatically. SCIM then manages access to that team:

IdP action	Sapling result
Create (assign the app)	Records the user. If an account with that email is already on one of your organization's Sapling teams, it is linked immediately; otherwise it links the first time the user signs in with SSO. An active: false sent with the create is applied.
Update profile	Stores the updated attributes, including a changed userName (for example, after an email change). The new userName must not belong to another user in your organization (409 otherwise).
Deactivate (active: false) or unassign	Removes the user from every Sapling team in your organization. Their seat is freed and Enterprise features stop working immediately.
Reactivate (active: true)	Restores the user's memberships on your organization's Sapling teams.
Delete	Revokes access like a deactivation and removes the user from pushed groups. The user no longer appears in SCIM reads (GET returns 404). Provisioning the same userName again restores the record, linked to the same Sapling account.

Deleting a user through SCIM does not erase their Sapling account or data. To do that, ask your team administrator or contact us.

Supported operations

Endpoint	Methods
/Users	GET (with filter=userName eq "<email>", or paged with startIndex/count), POST
/Users/{id}	GET, PUT, PATCH (active), DELETE
/Groups	GET (with filter=displayName eq "<name>", or paged), POST
/Groups/{id}	GET, PUT, PATCH (members add/remove/replace, displayName), DELETE

Pages return at most 100 resources.

Attributes

Attribute	Required	Notes
userName	Yes	Must be the user's email address, the same one they use to sign in with SSO. Matched case-insensitively.
active	No	Defaults to true.
name.givenName, name.familyName, displayName, emails, externalId	No	Stored and returned. Sapling does not require them.

No custom or extension attributes are required.

Groups

Group push is supported but not required. Assigning the Sapling app to users or groups in your IdP is enough to provision and deprovision. Pushed groups are mirrored in Sapling, but they do not map to Sapling roles: team admin and manager permissions are managed in Sapling.

Group membership affects access in one way. When a user is removed from a pushed group and belongs to no other pushed group, their access is revoked as if they had been deactivated. Adding a user to a pushed group restores their access. Deleting a pushed group in Sapling does not change any member's access: members are not deactivated, even if they belong to no other pushed group.

Group members must already be provisioned users. A request that adds a member Sapling has not provisioned, or replaces the member list with one that includes such a member, is rejected with 400, and none of that request's changes are applied. Removing an unknown member succeeds. Provision users (assign the app) before pushing a group that contains them.

To empty a group, send "members": [] or a PATCH that removes members. A PUT that omits members leaves the membership unchanged.

If you use group push, push only the group or groups that are assigned to the Sapling app.

Okta setup

1. In Okta, open your Sapling app integration (the app you use for SSO), go to General → App Settings, and enable SCIM provisioning.
2. On the Provisioning → Integration tab, set:
   • SCIM connector base URL: https://api.sapling.ai/scim/v2
   • Unique identifier field for users: userName
   • Supported provisioning actions: Push New Users, Push Profile Updates, Push Groups (optional)
   • Authentication Mode: HTTP Header, using the token Sapling provided as the Bearer token
3. Click Test Connector Configuration, then Save.
4. On Provisioning → To App, enable Create Users, Update User Attributes, and Deactivate Users.
5. Make sure the Okta username or email mapped to userName is the address users sign in to Sapling with.
6. Assign the app to a few test users first. Confirm that they appear and that deactivating one in Okta removes them from your Sapling team. Then assign the app to your full user population.
7. Optional: set up group push on the Push Groups tab only after the group's members have been provisioned (step 6).

Microsoft Entra ID (Azure AD) setup

1. In your Sapling enterprise application, open Provisioning and set Provisioning Mode to Automatic.
2. Set Tenant URL to https://api.sapling.ai/scim/v2 and Secret Token to the token Sapling provided. Click Test Connection.
3. Under Mappings, open the user mapping. Map userPrincipalName (or mail) to userName, keep the active mapping (Switch([IsSoftDeleted], ...)), and delete the other attribute mappings (displayName, name.*, emails, and so on). Entra sends profile changes as PATCH /Users/{id} requests, and Sapling's user PATCH supports only active. Sapling does not need the other attributes.
4. Set the scope to Sync only assigned users and groups, and start provisioning.

Testing

Sapling does not provide a separate SCIM sandbox. Before you assign the app to everyone, we recommend testing against production with a few test users from your directory. On request, Sapling can also issue a token for a separate test organization and team.