SCIM integration

Overview

PremiumEnterpriseSmart card

SCIM (System for Cross-domain Identity Management) is an integration that automates user provisioning for your company’s Brex account. The integration can manage Brex user accounts for your employees after being added to your identity provider. It can also disable users after they are removed from your identity provider.

Connecting your identity provider can help you automate user and spend management as you scale. In terms of user management, SCIM integrations allow you to automate adding, inviting, updating, or deactivating users and their details. Connecting your identity provider via SCIM also helps you with your spend management by automating spend limit assignment, syncing entities, providing insights into spending patterns, and connecting with your ERP.

Admins, and any other users with the “Manage HRIS connection” capability can use Brex’s SCIM integration to manually or automatically invite users to their Brex accounts. This lets you invite a large group of members of your organization, already established in your identity provider, to your Brex account. After inviting them, you can continue to manage their details in your identity provider; changes sync into Brex in real time.

Key SCIM features

• Add first, then invite: Provision users from your identity provider, add users to spend limits, and then choose who to invite when you’re ready.
• Configure access management settings: By default, these settings are OFF when your identity provider sends user data. After initial sync of user data from your identity provider, you can configure these settings to your needs.
  • Auto-invite: Set up custom rules to determine who to invite from your identity provider based on attributes such as entity, department, title, etc. When configuring auto-invite, you can configure the roles these users will have when invited.
  • Offboarding: By default, removing a user from your identity provider doesn't revoke their Brex access; you control when to deactivate. If you enable automatic offboarding in your identity provider, deactivation happens automatically when the user is removed upstream. Deactivation revokes Brex dashboard access and blocks spending on all active Brex cards, but doesn't lock or cancel the cards, so they can be transferred if needed. Spend limits for users who are the sole spenders will close automatically.
• Automated user updates: User information in Brex is automatically updated the moment your identity provider sends Brex an update, ensuring accurate and timely information and reducing manual overhead.

Fields available to sync

When you push data from your identity provider to Brex via SCIM, we can store all of the following data attributes:

• Email
• First name
• Last name
• Title (if available)
• Department (if available)
• Location (if available)
• Cost center (if available)
• Legal entity (if available)
• Other custom fields (see details in Connect SCIM section below)

Note: Anything marked “if available” can only be synced if supported by your identity provider and mapped appropriately for your provider (see examples below).

Connect SCIM

Step 1: In your Brex dashboard, click Team > Team settings > Connect SCIM.

Step 2: Follow the on-screen instructions to generate your SCIM bearer token. Store this token securely; you'll need it to configure your identity provider. The Brex SCIM base URL is https://scim.brex.com/v2 (also visible after connecting in the “...” menu).

Step 3: Once connected, you can manage your SCIM integration by clicking Team > SCIM settings. Here, you can auto-invite users to Brex from your SCIM integration, manage offboarding, and map legal entities (if needed). We’ll automatically sync any custom user fields from your identity provider (if configured).

Note: Users associated with unverified legal entities cannot be invited to Brex until the legal entity has passed verification.

If you need to restrict users added to Brex via SCIM by email domain, please contact your Brex representative.

To manage your custom user fields from your SCIM integration, go to Team and click Fields library. Here, you can review and manage the enablement of your custom user fields. To learn more about the Fields library, read this help article.

Disconnect SCIM

Step 1: Go to Team > SCIM settings.

Step 2: At the top of the navigation, click the “...” menu beside SCIM settings.

Step 3: Click Disconnect SCIM.

When you disconnect your SCIM integration, all employee information already stored in Brex will remain in your account, but any changes in your identity provider will no longer be synced going forward — including employee invitations and terminations. Employees invited prior to disconnecting will no longer be suspended when terminated in your identity provider.

Legal entity mapping

To map your identity provider legal entities via SCIM with your Brex legal entities, follow the instructions below.

Step 1: Navigate to the Team page and click SCIM settings.

Step 2: Select Entity mapping from the navigation on the left side of the page.

Step 3: Here, you’ll find identity provider synced entities on the left and Brex-created entities on the right. You’ll want to map each identity provider originated entity to a Brex entity, either by choosing one that exists or creating a new one (which will take you through entity verification). If you need to create a new legal entity, you may go to Team > Entities > Add entity. Learn more about managing entities here.

Managing custom fields

SCIM supports syncing custom user fields and those fields may be managed by following the steps below.

Step 1: Navigate to the Team page and click SCIM settings.

Step 2: Click Synced fields to view all of the fields synced by your identity provider.

Step 3: From here, you may opt to Disable field or Enable field. You may read more about managing custom user fields in the User fields section of this article.

Okta SCIM setup

You can connect an Okta SCIM account with your Brex account by following these steps (skip to step 7 if you have already configured SSO with SAML with Brex and have an app configured):

Step 1: Go to the Applications page in your Okta admin dashboard.

Step 2: Click Browse App Catalog to create a new SCIM application.

Step 3: Search for SCIM Bearer and choose the SCIM 2.0 Test App (OAuth Bearer Auth).

Step 4: Click Add Integration.

Step 5: Enter a name for your application, check the box to hide the application from users, and click Next.

Step 6: If not already, set Application username format to Okta username. Leave everything else as the default and click Done to create the application.

Step 7: Go to the Provisioning tab, click Configure API Integration, then check the Enable API integration check box.

Step 8: Enter https://scim.brex.com/v2 as the SCIM 2.0 Base Url and your SCIM bearer token configured in Brex as the OAuth Bearer token and click Test API Credentials to confirm the settings are correct.

Step 9: Go to the To App tab and click the checkbox to enable Create Users, Update User Attributes, and Deactivate Users (if you want to enable auto-deprovisioning). You can also verify mapping in the attribute mapping section below. The default mappings we expect are shown in the screenshot at the bottom of the page.

Okta attributes map to Brex as follows:

• Department: This maps to the department attribute in Brex.
• Cost Center: This maps to the cost center attribute in Brex.
• Division: This maps to legal entities in Brex.
  • Note: Legal entities are expected to already exist in Brex before employees can be mapped to them. If a user belongs to a division that doesn’t exist or is not mapped to an existing legal entity, they will be assigned the default entity. To create legal entities, please go to the Brex dashboard. You may map legal entities in Team > SCIM settings > Entity mappings.
• Manager value: This maps to the manager in Brex. For manager import, make sure to map the manager’s email or Okta user ID to the manager value. In most cases, the attribute value will be the “user.managerId” in Okta, but if it isn't, map the correct attribute here.
• Country: This maps to the location attribute in Brex by default. Okta supports this as a 2 character country code.
  • Any other value can be supplied as the location attribute in Brex by providing a custom profile mapping in Okta

You’ve now integrated Okta SCIM with your Brex account. You can test your setup by assigning the SCIM app to an Okta user to verify the user is provisioned in the Team page of your Brex dashboard.

Mapping a custom location attribute

Step 1: In your Brex SCIM app, go to Provisioning > Attribute Mappings and click Go to Profile Editor.

Step 2: Select Add Attribute.

Step 3: Define the attribute details for location.

• Data type = string
• Display name: Location
• Variable name: location
• External name: location
• External namespace: urn:ietf:params:scim:schemas:extension:brex:User
• Attribute type: Personal or Group

Step 4: In your Brex SCIM app, go to Provisioning > Attribute Mappings > Show Unmapped Mappings and click the pencil icon for Location.

Step 5: Map the relevant user attribute value from the Okta user profile to location (user.city is an example).

You’ve now integrated Okta SCIM with your Brex account. You can test your setup by assigning the SCIM app to an Okta user to verify the user is provisioned in the Teams page of your Brex dashboard.

Mapping custom attributes (custom fields)

Step 1: In your Brex SCIM app, go to Provisioning > Attribute Mappings and click Go to Profile Editor.

Step 2: Select Add Attribute.

Step 3: Define the attribute details for your custom field.

Data type = string

Display name: <Human friendly label shown in Okta UI>

Variable name: <An internal identifier used by Okta in expressions and mappings. Often the same as External name.>

External name: <The field name to be sent to Brex.>

External namespace: urn:ietf:params:scim:schemas:extension:brex:custom:User

Attribute type: Personal or Group

Step 4: In your Brex SCIM app, go to Provisioning > Attribute Mappings > Show Unmapped Mappings and click the pencil icon for your custom field.

Step 5: Map the relevant user attribute value from the Okta user profile to your custom field.

Automatic user off-boarding

If you enable “Deactivate users,” your SCIM integration will automatically off-board users in Brex when they are unassigned to the app in Okta (or their Okta account is deactivated). Users with “Archived,” “Invited,” or “Not invited” statuses will be deleted in Brex and no longer visible in the Brex Dashboard. Users with “Active” statuses will be deactivated in Brex but still visible in the Brex Dashboard.

If a user is reactivated in Okta, they will be reactivated if previously deactivated. If they were deleted by SCIM, a new user record will be created in Brex

Recommended attribute mappings

Microsoft Entra ID Setup

You can connect a Microsoft Entra ID tenant with your Brex account by following these steps (skip to step 5 if you have already configured SSO with Brex):

Step 1: Go to the Applications -> Enterprise applications page in your Microsoft Entra ID admin dashboard.

Step 2: Click New application to create a new application for your SCIM integration with Brex (or choose an existing application if you have configured a single sign-on (SSO) application to log in to Brex).

Step 3: Click Create your own application.

Step 4: Enter a name for your application, choose Integrate any other application you don’t find in the gallery (Non-gallery), and click Create.

Step 5: Click on Provisioning.

Step 6: Select Provisioning under Manage. Choose the Automatic Provisioning Mode. Enter https://scim.brex.com/v2 as the Tenant URL. Enter your SCIM bearer token configured in Brex as the Secret Token and click Test Connection to confirm the settings are correct. Click Save.

Step 7: Manage your user’s mappings by selecting Provision Microsoft Entra ID Users.

Set the userName target attribute to the mail source attribute from Entra ID to make sure the email identifier is used for the profile instead of the userPrincipalName. Without changing this, Brex will not be able to match the users within Brex. Click OK and then Save.

Entra ID attributes map to Brex as follows:

• Department: This maps to the department attribute in Brex.
• Cost Center: This maps to the cost center attribute in Brex.
• Division: This maps to legal entities in Brex. Entra ID does not map this by default.
  • Note: Legal entities are expected to already exist in Brex before employees can be mapped to them. If a user belongs to a division that doesn’t exist or is not mapped to an existing legal entity, they will be assigned the default entity. To create legal entities, please go to the Brex dashboard. You may map legal entities in Team > SCIM settings > Entity mappings.
• Manager value: This maps to the manager email in Brex. For manager import, make sure to map the manager’s ID reference to the manager value.
• Country: This maps to the location attribute in Brex by default.
  • Any other value can be supplied as the location attribute in Brex by providing a custom profile mapping in Entra ID

To map the manager, edit the attribute list in Attribute mapping > Provision Microsoft Entra ID Users for the application and add a new reference attribute urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value that has a referenced object attribute of urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.id.

You’ve now integrated Entra ID SCIM with your Brex account. You can test your setup by assigning the SCIM app to an Entra ID user to verify the user is provisioned in the Team page of your Brex dashboard.

Mapping custom attributes (custom fields)

Step 1: Select the Attribute mapping tab and click on Provision Microsoft Entra ID Users for the application.

Step 2: Scroll to the bottom, click Show advanced options, then click Edit attribute list for <your app>.

Step 3: Add a new attribute at the bottom

Name: urn:ietf:params:scim:schemas:extension:brex:custom:User:<customFieldName>

Type: String

Step 4: Click Save at the top to register the new attribute.

Step 5: Go back to Attribute mapping and click Add New Mapping.

Step 6: Map your value to your custom user field; the source attribute is what you want to map to the custom field. For the rest of the options, the defaults are fine in our experience but you may configure them based on your needs.

Step 7: Click OK to save your mapping.

Automatic user offboarding for Entra ID

If you set the “active” attribute mapping, your SCIM integration will automatically offboard users in Brex when they are soft deleted in Entra. Users with “Archived,” “Invited,” or “Not invited” statuses will be deleted in Brex, and they will no longer be visible in the Brex dashboard. Users with “Active” statuses will be deactivated, and they will still be visible in the Brex dashboard.

If a user is reactivated in Entra ID, they will be reactivated if previously deactivated. It is possible they won’t be re-added to any spend limits they may have been removed from automatically.

If they were deleted by SCIM, a new user record will be created in Brex.

Recommended attribute mappings