SCIM integration

SCIM integration

Overview

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

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:

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

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.

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.

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.

Okta SCIM setup

You can connect an Okta SCIM account with your Brex account by following these steps:

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.

Okta attributes map to Brex as follows:

Step 10: Go to the Assignments tab and assign a user or a group to the SCIM application using Assign > Assign to People or Assign to Groups. Assigning users or groups in Okta provisions them in Brex.

You've now integrated Okta SCIM with your Brex account. To verify your setup, confirm the assigned 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.
Step 4: In your Brex SCIM app, go to Provisioning > Attribute Mappings > Show Unmapped Mappings and click the pencil icon for Location.

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

If you enable “Deactivate users,” your SCIM integration will automatically off-board users in Brex when they are unassigned to the app in Okta. 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.

Recommended attribute mappings

Attribute Attribute type Value Apply on
Username
userName
Personal Configured in Sign On settings
Given name
givenName
Personal user.firstName Create and update
Family name
familyName
Personal user.lastName Create and update
Middle name
middleName
Personal user.middleName Create and update
Honorific prefix
honorificPrefix
Personal user.honorificPrefix Create and update
Honorific suffix
honorificSuffix
Personal user.honorificSuffix Create and update
Email
email
Personal user.email Create and update
Primary email type
emailType
Personal (user.email != null && user.email !='') ? 'work' : '' Create and update
Title
title
Personal user.title Create and update
Display name
displayName
Personal user.displayName Create and update
Nickname
nickname
Personal user.nickName Create and update
Profile Url
profileUrl
Personal user.profileUrl Create and update
Primary phone
primaryPhone
Personal user.primaryPhone Create and update
Primary phone type
primaryPhoneType
Personal (user.primaryPhone != null && user.primaryPhone != '') ? 'work' : '' Create and update
Address type
addressType
Personal (user.streetAddress != null && user.streetAddress != '') ? 'work' : '' Create and update
Street address
streetAddress
Personal user.streetAddress Create and update
Locality
locality
Personal user.city Create and update
Region
region
Personal user.state Create and update
Postal Code
postalCode
Personal user.zipCode Create and update
Country
country
Personal user.countryCode Create and update
Formatted
formatted
Personal user.postalAddress Create and update
Preferred language
preferredLanguage
Group user.preferredLanguage Create and update
Locale Name
locale
Group user.locale Create and update
Time zone
timezone
Group user.timezone Create and update
User type
userType
Group user.userType Create and update
Employee number
employeeNumber
Personal user.employeeNumber Create and update
Cost center
costCenter
Group user.costCenter Create and update
Organization
organization
Group user.organization Create and update
Division
division
Group user.division Create and update
Department
department
Group user.department Create and update
Manager value
managerValue
Personal user.managerid Create and update
(optional) Location
location
Personal or Group Expression from Okta user profile Create and update

Microsoft Entra ID Setup

You can connect a Microsoft Entra ID tenant with your Brex account by following these steps:

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.

To map the manager, edit the attribute list in Attribute mapping

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 .
Step 3: Add a new attribute at the bottom

Name: urn:ietf:params:scim:schemas:extension:brex:custom:User:

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.

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.

Recommended attribute mappings

Attribute Recommended Microsoft Entra ID Value
userName mail
active Switch([IsSoftDeleted], , "False", "True", "True", "False")
name.givenName givenName
name.familyName surname
emails[type eq “work”].value mail
title jobTitle
displayName displayName
phoneNumbers[type eq "work"].value state
addresses[type eq "work"].region city
addresses[type eq "work"].postalCode postalCode
addresses[type eq "work"].country country
addresses[type eq "work"].formatted physicalDeliveryOfficeName
userType user.userType
externalId objectId
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber employeeId
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division companyName
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department department
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value manager (reference)
urn:ietf:params:scim:schemas:extension:brex:User:location