# SCIM integration

Get answers to all of your questions regarding Brex

**URL Source:** https://www.brex.com/support/scim-integration

---

## Overview

<!-- plans: Premium, Enterprise, Smart 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](https://www.brex.com/custom-roles) 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](https://www.brex.com/add-and-invite-users) 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](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](https://www.brex.com/accounting-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](https://www.brex.com/multi-entity-accounts).



### 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](https://www.brex.com/accounting-fields) 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)_.

![SCIM 2](https://brand.brex.com/asset/8899e7ef-67a1-4d0e-a121-f0ce32ee7704/thumbnail/webimage-SCIM-2)

**Step 4**: Click _Add Integration_.

![SCIM 1](https://brand.brex.com/asset/8229f68e-16c1-42ae-966e-029fca5467b9/thumbnail/webimage-SCIM-1)

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

![SCIM 4](https://brand.brex.com/asset/799f64cd-aa96-4ffd-8239-52db50254b37/thumbnail/webimage-SCIM-4)

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

![SCIM 6](https://brand.brex.com/asset/00802b6c-951a-4ff2-9776-7efa05cb591f/thumbnail/webimage-SCIM-6)

**Step 7**: Go to the _Provisioning_ tab, click _Configure API Integration_, then check the _Enable API integration_ check box.

![SCIM 5](https://brand.brex.com/asset/2d23295d-5b83-47ff-9a40-b466abf90ba7/thumbnail/webimage-SCIM-5)

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

![SCIM 7](https://brand.brex.com/asset/dc16ac8e-084b-4016-ab1c-134e0fb57b25/thumbnail/webimage-SCIM-7)

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

![SCIM 8](https://brand.brex.com/asset/ad76b796-9f90-4577-bf2e-a28e9c97d822/thumbnail/webimage-SCIM-8)

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

![HC - Okta SCIM 06](https://brand.brex.com/m/2da532c6c4761835/webimage-HC-Okta-SCIM-06.png)

**Step 2**: Select _Add Attribute_.

![HC - Okta SCIM 07](https://brand.brex.com/m/e2d4b371dab471/webimage-HC-Okta-SCIM-07.png)

**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

![HC - Okta SCIM 07](https://brand.brex.com/m/395f25c643ddd445/webimage-HC-Okta-SCIM-07.png)

**Step 4:** In your Brex SCIM app, go to _Provisioning _> _Attribute Mappings_ > _Show Unmapped Mappings_ and click the pencil icon for _Location_.

![HC - Okta SCIM 09](https://brand.brex.com/m/77a0bf46c5423a79/webimage-HC-Okta-SCIM-09.png)

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

![HC - Okta SCIM 10](https://brand.brex.com/m/1a8a534a7a785ddc/webimage-HC-Okta-SCIM-10.png)

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

![SCIM 9](https://brand.brex.com/asset/8b863f1e-cd30-481c-83d6-5192547f4b11/thumbnail/webimage-SCIM-9)

**Step 2**: Select _Add Attribute_.

![SCIM 10](https://brand.brex.com/asset/18b00ec7-fcb4-4165-899c-2506df6323ae/thumbnail/webimage-SCIM-10)

**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

| 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.steetAddress != '') ? '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 |
| Manager display name   managerDisplayName | Personal | user.manager | 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 (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_.

![Entra 1](https://brand.brex.com/asset/e1c4c6e6-1fbf-4243-a5db-fba7fff82fd5/thumbnail/webimage-Entra-1)

**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_.

![Entra 6](https://brand.brex.com/asset/94dc4bbc-037f-4736-b62b-63e44f97fd8d/thumbnail/webimage-Entra-6)

**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_.

![Entra 2](https://brand.brex.com/asset/4ef8393e-c59c-4a80-8cb5-f0d04ec4d384/thumbnail/webimage-Entra-2)

**Step 7**: Manage your user’s mappings by selecting _Provision Microsoft Entra ID Users_.

![Entra 3](https://brand.brex.com/asset/cd080f03-4558-4c3e-a6ed-7e32ea163374/thumbnail/webimage-Entra-3)

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 4](https://brand.brex.com/asset/fa1d445b-1f09-470d-9ec5-6677965f64dc/thumbnail/webimage-Entra-4)

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

![Entra 5](https://brand.brex.com/asset/85a3d600-1434-4d65-b3fd-4bfc146cf616/thumbnail/webimage-Entra-5)

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

| 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_ |  |