Skip to main content
SCIM (System for Cross-domain Identity Management) provisioning lets your identity provider (IdP) control who belongs to your Braintrust organization and, optionally, which permission groups they belong to. Instead of inviting and removing members by hand, you manage groups in your identity provider and Braintrust follows.
SCIM provisioning is in private preview, available to a limited set of customers. To request access, contact Braintrust.
SCIM provisioning is only available on the Enterprise plan.

​
How SCIM provisioning works

Braintrust derives access from the SCIM groups a user belongs to:
  • Organization membership: You map one SCIM group to your Braintrust organization. Users in that group are members of the organization, and users who leave it are removed.
  • Permission groups: You can optionally map each Braintrust permission group to its own SCIM group. A user is added to a permission group when they are in the mapped SCIM group and are a member of the organization.
Braintrust only changes organizations and permission groups that you explicitly map. See Unmapped organizations and permission groups. SCIM provisioning replaces domain mappings for an organization rather than working alongside them. Once SCIM manages an organization’s membership, domain mappings no longer add users to it, so a user who signs in with a matching email domain joins only if your identity provider puts them in the mapped SCIM group. Only members of the Owners permission group can view or change SCIM settings.

​
Connect your identity provider

Braintrust connects your identity provider to your organization for you. Contact support@braintrust.dev with the name or ID of each Braintrust organization you want to provision. A Braintrust support engineer sends you two values through a secure, short-lived link:
  • A SCIM endpoint URL.
  • A bearer token.
The bearer token covers every Braintrust organization your identity provider manages. If you manage more than one Braintrust SSO application in your IdP, create a separate application dedicated to SCIM rather than enabling SCIM on one of them. Settings > SCIM appears under Organization for every Enterprise organization, and invites you to contact support until your identity provider is connected.

​
Set up provisioning in your identity provider

These steps enable SCIM on your existing Braintrust SSO application. If you created a dedicated SCIM application instead, apply the same provisioning settings to that application.

​
Okta

1

Enable SCIM provisioning

From the Okta admin dashboard, open your Braintrust SSO application and select the General tab. Click Edit, then enable SCIM under Provisioning.
2

Configure the connector

Open the Provisioning tab that now appears and enable the SCIM integration. Set SCIM connector base URL to the endpoint URL Braintrust sent you, set Unique identifier field for users to userName, and enter the bearer token in the API Token field.
3

Choose the actions Okta pushes

Enable Push New Users, Push Profile Updates, and Push Groups. Click Test API Credentials to verify the connection, then click Save.
4

Enable provisioning to Braintrust

Under To App, enable Create Users, Update User Attributes, and Deactivate Users, then click Save.

​
Microsoft Entra ID

1

Open the provisioning settings

In the Microsoft Entra admin center, go to Enterprise applications and select your existing Braintrust application. Select Provisioning, then set Provisioning Mode to Automatic.
2

Enter the credentials

Under Admin Credentials, set Tenant URL to the endpoint URL Braintrust sent you and Secret Token to the bearer token. Select Test Connection, then Save.
3

Test with a small group

Create a group containing a single test user and assign it to the Braintrust application under Users and groups. In the provisioning settings, set Scope to Sync only assigned users and groups, confirm under Mappings that both user and group provisioning are enabled, and confirm that Entra maps your chosen user identifier to the SCIM userName attribute.
4

Start provisioning

Use Provision on demand to test the user, then the test group. Once both succeed, select Start provisioning to begin ongoing synchronization.
SCIM is now enabled, but no users reach Braintrust until you provision a group from your IdP and map it in your Braintrust SCIM settings.

​
Provision a group to Braintrust

SCIM groups appear in the Braintrust group pickers only after your IdP provisions them. For each group you plan to map:
  1. Create or select a group in your IdP and add every user who should be covered by that mapping.
  2. Make sure every member of the group is assigned to your Braintrust application in your IdP.
  3. Provision the group. In Okta, add it under Push Groups and select Push now. In Microsoft Entra ID, use Provision on demand, or start provisioning and wait for the group to sync.
Reload the Braintrust SCIM settings page and the group appears in the picker.
Create these groups and populate them with the right members before you configure SCIM in Braintrust, so the whole setup can be completed in one sitting. In Okta, keep the group you assign to the application separate from the group you push.

​
Configure Braintrust

Go to Settings > SCIM. Until you turn on Enable SCIM updates, the page guides you through three numbered steps: Organization membership, Permission groups, and SCIM updates. Braintrust ignores incoming events from your IdP and changes no memberships until you enable SCIM updates in the last step, so you can map groups and review the results first. Permission groups and SCIM updates appear once you select an organization membership group. Each step that changes who SCIM manages runs a membership check against your identity provider before you can save it.

​
Map organization membership

Create one SCIM group per Braintrust organization you administer, even if you administer only one. To map it:
  1. Under Organization membership, select the SCIM group whose members should belong to this Braintrust organization. Braintrust checks every current organization member against it.
  2. Review the check, then click Save. The button is enabled once the check passes or you acknowledge the members who need attention.
Changing the organization membership group makes the new group authoritative for this organization. Once Enable SCIM updates is on, anyone who isn’t in the new SCIM group is removed from the organization and their API keys for that organization are deleted. Review everyone the check lists under Needs attention before you click Change group.
To change the group:
  1. Click Change.
  2. In the Change organization membership group dialog, select the new SCIM group. Braintrust checks every current organization member against it.
  3. Review the check, then click Change group. The button is enabled once the check passes or you acknowledge the results.
To stop managing organization membership through SCIM:
  1. Click Change.
  2. Clear the group so that the picker shows No group (stop managing membership).
  3. Click Change group. This also turns off Enable SCIM updates, and no one is removed from the organization.
If the organization membership SCIM group is deleted in your identity provider, the group field highlights in red and a warning banner at the top of the page lists Organization membership. Click Change to choose its replacement. SCIM groups are matched by ID, not name, so a new group with the same name doesn’t replace the deleted one automatically.

​
Check members

A membership check compares Braintrust members against your identity provider and a SCIM group. A member is Ready only when they’re active in your identity provider application, linked to the correct sign-in identity, in the identity provider application connected to this organization, and in the SCIM group. Every other member is listed under Needs attention with the reason, such as:
  • Deactivated in your identity provider application
  • Found in a different identity provider application
  • Not found in your identity provider application
  • Not in the SCIM group
  • Linked to a different sign-in identity or Braintrust account
  • Has API keys but hasn’t signed in yet, so SCIM can’t manage the account
Braintrust runs the check before you save an organization membership group, add or replace a permission group mapping, or turn on SCIM updates. That step’s save button is enabled when every member is Ready. To resolve members who need attention:
  1. Review the reason listed for each member under Needs attention.
  2. Resolve each issue in your identity provider.
  3. Click Refresh to run the check again.
To continue without resolving every issue, select the checkbox confirming that you’ve reviewed the members who need attention. Refreshing the check clears the checkbox.
Membership checks cover up to 1,000 members. With more, the check reports “Too many members to check (limit 1,000)” and can’t verify anyone, and Check members… doesn’t appear next to Change. If a check can’t verify members, for this or any other reason, you can continue only by selecting the checkbox confirming that some members could not be verified.
You can also run the check at any time. Once a membership group is set, Check members… appears next to Change and checks every current organization member against the saved group. Each permission group mapping has its own check, described under Map permission groups.

​
Map permission groups

The Permission groups step is optional. Choose how members get their permission groups: add every newly provisioned member to a default group, or turn on Manage permission groups via SCIM and map each permission group to a SCIM group. If you map permission groups before you enable SCIM updates, the check that runs when you turn updates on includes them.

​
Set a default permission group

If you don’t plan to manage permission groups through SCIM, use Default group to choose the permission group that newly provisioned members are added to. This setting is available when Manage permission groups via SCIM is off.

​
Manage permission groups via SCIM

To manage permission group membership from your identity provider:
  1. Turn on Manage permission groups via SCIM. This toggle is available once an organization membership group is set.
  2. Click Add mapping.
  3. Select a Braintrust permission group and the SCIM group to pair it with. Braintrust checks the permission group’s current members against the SCIM group.
  4. Review the check, then click Add mapping. The button is enabled once the check passes or you acknowledge the results.
Each permission group maps to one SCIM group. A user must also be in the organization membership group to be added to a mapped permission group.
Adding or replacing a mapping makes the SCIM group authoritative for that permission group. Once Enable SCIM updates is on, anyone in the Braintrust group who isn’t in the mapped SCIM group is removed from it. Review everyone the check lists under Needs attention before you save the mapping.
If Enable SCIM updates is already on and you have saved mappings, turning on Manage permission groups via SCIM opens a confirmation dialog, because your saved mappings start applying immediately. Braintrust checks every saved mapping, and Turn on is enabled once the checks pass or you acknowledge the results. Each mapping row has these controls:
  • Check members… runs the same checks as the organization check, and also requires each permission group member to be in both the organization membership SCIM group and the mapped SCIM group. Members who pass show as Ready, and everyone else is listed under Needs attention with the reason. It can’t check a permission group with more than 1,000 members.
  • Remove stops syncing that permission group after you confirm. Braintrust doesn’t change who is in the group, and current members keep their access.

​
Replace a deleted SCIM group

If a mapped SCIM group is deleted in your identity provider, its row highlights in red, is marked Deleted in your identity provider, and shows the deleted group’s ID. The warning banner at the top of the page also lists the mapping. To replace it:
  1. Click Replace on the row.
  2. Select the replacement SCIM group. If exactly one unmapped SCIM group has the same name as the deleted group, it’s pre-selected. Confirm it’s the replacement you created in your identity provider.
  3. Review the check, then click Replace mapping. The button is enabled once the check passes or you acknowledge the results.

​
Enable SCIM updates

Review the membership of every mapped SCIM group and confirm that each one grants the access you intend. Then turn on Enable SCIM updates. This toggle is available once an organization membership group is set. Turning on the toggle opens the Enable SCIM updates dialog instead of saving immediately. Braintrust checks your organization members against the organization membership group and, if Manage permission groups via SCIM is on, the members of each mapped permission group against its SCIM group. Each check appears as its own row. Click Details on a row to see the members who need attention. Enable SCIM updates is enabled once every check passes or you acknowledge the results.
Once SCIM updates are on, changes from your identity provider add and remove members of this organization and its mapped permission groups. Members removed from the organization lose their API keys for it.
While the toggle is off, Braintrust ignores incoming events from your IdP. Turning it off takes effect immediately.

​
What SCIM events change

With Enable SCIM updates on, these actions in your IdP update Braintrust:
  • A user is added to the organization membership group. The user is provisioned into the Braintrust organization and added to any mapped permission groups they qualify for.
  • A user is removed from the organization membership group. The user is removed from the organization, and their API keys for that organization are deleted.
  • A user is added to or removed from a mapped permission group’s SCIM group. The user is added to or removed from the corresponding Braintrust permission group.
  • A user is deactivated in the IdP. The user is removed from every Braintrust organization that IdP manages, and their API keys for those organizations are deleted.
To force a full resynchronization between your IdP and Braintrust, provision the groups again. In Okta, select Push now under Push Groups. In Microsoft Entra ID, use Provision on demand, or let the scheduled provisioning cycle run.

​
Manual membership changes

Once Enable SCIM updates is on and an organization membership group is set, your identity provider becomes the source of truth for membership. Braintrust disables the controls that would let the two drift apart:
  • On Settings > Members, Invite and the remove control are disabled.
  • On Settings > Permission groups, adding and removing members of a mapped group is disabled.
  • In the Edit permission groups dialog on a member’s row, mapped groups can’t be added or removed.
Hovering a disabled control explains why: “Membership is managed by your identity provider (SSO).” Owners also see how to lift the lock. The lock applies to the API as well as the UI. PATCH /v1/organization/members is rejected with a 403 for a managed organization, and so is a PATCH /v1/group/{group_id} that changes a managed group’s members through add_member_users, remove_member_users, add_member_groups, or remove_member_groups. Other fields on that endpoint, such as the group’s name and description, are unaffected. Two exceptions keep working:
  • Unmapped permission groups. A permission group locks only when Manage permission groups via SCIM is on and that group is mapped to a SCIM group. Everything else stays manually editable.
  • Service accounts. Because they don’t exist in your identity provider, you can add and remove service accounts by hand even while SCIM manages the organization.
To make a manual change, turn off Enable SCIM updates, make the change, then turn it back on. Turning it back on runs the membership check again, so a member you added by hand who isn’t in the matching SCIM group appears under Needs attention. Braintrust reconciles each user against your identity provider when it next receives an event for them, so a manual change that conflicts with your SCIM groups doesn’t persist.

​
Unmapped organizations and permission groups

Braintrust only adds and removes access for organizations and permission groups that are explicitly mapped on the SCIM settings page. Anything you haven’t mapped is left alone:
  • If a user belongs to a Braintrust organization that has no organization membership group configured, deactivating that user in your IdP does not remove them from that organization.
  • If your organization contains permission groups with no SCIM mapping, SCIM events do not add or remove members from those groups.
Braintrust also never removes access based on missing group data. If your IdP sends an event without group information, Braintrust makes no changes rather than treating the absent data as an empty group.

​
Next steps

  • Set up SSO so provisioned members can sign in with your identity provider.
  • Review access control to decide which permission groups to map.
  • Learn how API keys inherit their user’s permissions.