# 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:

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

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

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](/content/support/multi-entity-accounts/index.html).

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

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