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
- 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:
- 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.
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:
- 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.
- 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.
- Country: This maps to the location attribute in Brex by default.
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 |
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 | |
| active | Switch([IsSoftDeleted], , "False", "True", "True", "False") |
| name.givenName | givenName |
| name.familyName | surname |
| emails[type eq “work”].value | |
| 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 |