> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM provisioning

> Provision organization members and permission groups from your identity provider, and keep Braintrust access in sync with it.

export const feature_1 = "SCIM provisioning"

export const verb_1 = "is"

export const feature_0 = "SCIM provisioning"

export const verb_0 = "is"

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.

<Warning>
  {feature_1} {verb_1} in [private preview](/docs/feature-lifecycle), available to a limited set of customers. To request access, [contact Braintrust](https://braintrust.dev/contact).
</Warning>

<Note>
  {feature_0} {verb_0} only available on the [Enterprise plan](/docs/plans-and-limits#plans).
</Note>

## 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](#unmapped-organizations-and-permission-groups).

SCIM provisioning replaces [domain mappings](/docs/admin/authentication#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](/docs/admin/access-control) can view or change SCIM settings.

## Connect your identity provider

Braintrust connects your identity provider to your organization for you. Contact [support@braintrust.dev](mailto: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.

**<Icon icon="settings-2" /> Settings** > [**<Icon icon="contact-round" /> SCIM**](https://www.braintrust.dev/app/~/configuration/org/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

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Enable provisioning to Braintrust">
    Under **To App**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**, then click **Save**.
  </Step>
</Steps>

### Microsoft Entra ID

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Start provisioning">
    Use **Provision on demand** to test the user, then the test group. Once both succeed, select **Start provisioning** to begin ongoing synchronization.
  </Step>
</Steps>

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.

<Tip>
  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.
</Tip>

## Configure Braintrust

Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="contact-round" /> SCIM**](https://www.braintrust.dev/app/~/configuration/org/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](#check-members) 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](#check-members), then click **Save**. The button is enabled once the check passes or you acknowledge the members who need attention.

<Warning>
  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**.
</Warning>

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](#check-members), 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.

<Note>
  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.
</Note>

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).

### 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 <Icon icon="plus" /> **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](#check-members), 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.

<Warning>
  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.
</Warning>

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](#check-members), 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.
* <Icon icon="trash" /> **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 <Icon icon="refresh-cw" /> **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](#check-members), 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.

<Warning>
  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.
</Warning>

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 **<Icon icon="settings-2" /> Settings** > [**<Icon icon="users-round" /> Members**](https://www.braintrust.dev/app/~/configuration/org/team), **Invite** and the <Icon icon="trash-2" /> remove control are disabled.
* On **<Icon icon="settings-2" /> Settings** > [**<Icon icon="shield-check" /> Permission groups**](https://www.braintrust.dev/app/~/configuration/org/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](#check-members) 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](/docs/admin/authentication#single-sign-on-sso) so provisioned members can sign in with your identity provider.
* Review [access control](/docs/admin/access-control) to decide which permission groups to map.
* Learn how [API keys](/docs/admin/authentication#api-authentication) inherit their user's permissions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.