Brex User Management API Guide

Auth method: OAuth 2.0 (user tokens) or static API tokens (service accounts)

Setup steps

1. Navigate to Brex Dashboard > Developer > API Keys.
2. For machine-to-machine access, create a static API token and store it securely.
3. For OAuth 2.0 user-delegated access, register an OAuth application in the Brex developer portal to obtain client_id and client_secret.
4. Redirect users to Brex authorization endpoint; exchange the returned code for an access token.
5. Include the token in all requests as: Authorization: Bearer .

Required scopes

List Users

• Method: GET
• URL: https://platform.brexapis.com/v2/users
• Watch out for: Pagination is cursor-based; iterate next_cursor until null to retrieve all users.

Request example

GET /v2/users?cursor=<cursor_token>
Authorization: Bearer <token>

Response example

{
  "items": [{"id": "usr_123", "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "status": "ACTIVE"}],
  "next_cursor": "abc123"
}

Get User by ID

• Method: GET
• URL: https://platform.brexapis.com/v2/users/{id}
• Watch out for: Returns 404 if user does not exist or token lacks team scope.

Request example

GET /v2/users/usr_123
Authorization: Bearer <token>

Response example

{
  "id": "usr_123",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "status": "ACTIVE",
  "department_id": "dep_456"
}

Get Current User (Me)

• Method: GET
• URL: https://platform.brexapis.com/v2/users/me
• Watch out for: Returns the user associated with the OAuth token, not a service account.

Request example

GET /v2/users/me
Authorization: Bearer <token>

Response example

{
  "id": "usr_789",
  "first_name": "John",
  "email": "john@example.com",
  "status": "ACTIVE"
}

Invite User

• Method: POST
• URL: https://platform.brexapis.com/v2/users
• Watch out for: Requires team write scope. Brex sends an invitation email to the new user automatically.

Request example

POST /v2/users
Authorization: Bearer <token>
Content-Type: application/json
{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "manager_id": "usr_001"
}

Response example

{
  "id": "usr_123",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "status": "ACTIVE"
}

Update User

• Method: PUT
• URL: https://platform.brexapis.com/v2/users/{id}
• Watch out for: Setting status to INACTIVE deactivates the user. This is the deprovisioning mechanism via the REST API.

Request example

PUT /v2/users/usr_123
Authorization: Bearer <token>
Content-Type: application/json
{
  "status": "INACTIVE"
}

Response example

{
  "id": "usr_123",
  "status": "INACTIVE"
}

List Departments

• Method: GET
• URL: https://platform.brexapis.com/v2/departments
• Watch out for: Department IDs are needed when assigning users to departments during create/update.

Request example

GET /v2/departments
Authorization: Bearer <token>

Response example

{
  "items": [{"id": "dep_456", "name": "Engineering"}],
  "next_cursor": null
}

List Locations

• Method: GET
• URL: https://platform.brexapis.com/v2/locations
• Watch out for: Location IDs are needed when assigning users to office locations.

Request example

GET /v2/locations
Authorization: Bearer <token>

Response example

{
  "items": [{"id": "loc_789", "name": "San Francisco HQ"}],
  "next_cursor": null
}

Set User Limit

• Method: POST
• URL: https://platform.brexapis.com/v2/users/{id}/limit
• Watch out for: Amount is in the smallest currency unit (cents for USD). Requires team write scope.

Request example

POST /v2/users/usr_123/limit
Authorization: Bearer <token>
Content-Type: application/json
{
  "monthly_limit": {"amount": 500000, "currency": "USD"}
}

Response example

{
  "id": "usr_123",
  "monthly_limit": {"amount": 500000, "currency": "USD"}
}

• Rate limits: Brex enforces rate limits per API token. Exact numeric limits are not publicly documented in detail.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: When rate limited, Brex returns HTTP 429. Clients should respect Retry-After header. Brex recommends exponential backoff.
• Pagination method: cursor
• Default page size: 0
• Max page size: 0
• Pagination pointer: cursor

• Webhooks available: Yes
• Webhook notes: Brex supports webhooks for real-time event notifications. Webhooks are configured via the Brex developer portal or API.
• Alternative event strategy: Poll the /v2/users endpoint with cursor pagination for environments where webhooks are not feasible.
• Webhook events: user.created, user.updated, user.deactivated, card.created, card.updated, transaction.created, expense.created, expense.updated

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Premium or Enterprise

• Endpoint: https://platform.brexapis.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PUT /Groups/{id}, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• Requires SSO (SAML) to be configured before enabling SCIM.
• Supported IdPs are Okta and Microsoft Entra ID (Azure AD); Google Workspace SCIM support is not confirmed in official docs.
• SCIM provisioning requires Premium plan or higher.
• Group push maps to Brex departments; not all department attributes may be supported.
• Deprovisioning via SCIM sets user status to INACTIVE but does not delete the user record.

Provisioning a new employee via API requires a POST to /v2/users with first_name, last_name, email, manager_id, department_id, and location_id. Department and location IDs must be fetched first from /v2/departments and /v2/locations respectively.

Note that Brex automatically sends an invitation email on user creation and there is no API parameter to suppress this - verify the email address before the POST.

Deprovisioning is handled by a PUT to /v2/users/{id} with {"status": "INACTIVE"}. This deactivates dashboard access but does not cancel cards or delete the user record. Cards must be managed separately via the Cards API. There is no DELETE endpoint for users.

SCIM 2.0 is available at https://platform.brexapis.com/scim/v2 for Okta and Microsoft Entra ID on Premium or Enterprise plans. SAML SSO must be fully configured and tested before the SCIM token is generated - enabling SCIM without active SSO causes provisioning failures. Group push maps to Brex departments; not all department attributes are guaranteed to sync. Google Workspace SCIM support is not confirmed in official documentation.

Provision a new employee

1. Authenticate with a service account token or OAuth token with team write scope.
2. Optionally, GET /v2/departments and GET /v2/locations to retrieve IDs for the user's department and location.
3. POST /v2/users with first_name, last_name, email, manager_id, department_id, location_id, and title.
4. Brex sends an invitation email to the new user automatically.
5. Optionally, POST /v2/users/{id}/limit to set a monthly spend limit.

Watch out for: Invitation email is sent automatically and cannot be suppressed via the REST API. Ensure the email address is correct before creating the user.

Deprovision a departing employee

1. Authenticate with a token with team write scope.
2. GET /v2/users to find the user's id by email if not already known.
3. PUT /v2/users/{id} with body {"status": "INACTIVE"} to deactivate the user.
4. Verify the response shows status: INACTIVE.
5. Optionally, retrieve and reassign or cancel any active cards associated with the user via the Cards API.

Watch out for: Deactivation does not delete the user record or cancel cards automatically. Cards must be managed separately.

Sync users via SCIM with Okta

1. Ensure Brex Premium or Enterprise plan is active.
2. Configure SAML SSO in Brex Dashboard under Settings > Security > SSO before enabling SCIM.
3. In Brex Dashboard, navigate to Settings > Security > SCIM and generate a SCIM token.
4. In Okta, add the Brex application from the Okta Integration Network.
5. In the Okta Brex app, go to Provisioning > Integration and enter the SCIM base URL (https://platform.brexapis.com/scim/v2) and the SCIM token.
6. Enable provisioning features: Create Users, Update User Attributes, Deactivate Users.
7. Assign users or groups in Okta to push to Brex.

Watch out for: SSO must be fully configured and tested before enabling SCIM. Enabling SCIM without SSO active will cause provisioning failures.

The most significant API caveat is the SSO/SCIM ordering dependency: SCIM provisioning cannot be enabled before SSO is live, and misconfiguring this sequence produces silent failures rather than actionable errors. Teams that build SCIM-based automation before completing SSO setup will encounter deprovisioning gaps that are not immediately visible in the Brex dashboard.

OAuth scopes must be declared at authorization time and cannot be added to an existing token - a scope omission requires a full re-authorization flow. Static API tokens do not expire, which simplifies service account management but creates a rotation hygiene risk if tokens are not actively managed.

The /v2/users/me endpoint returns the token owner and is only meaningful for OAuth user tokens; calling it with a service account token does not return a useful identity context.

Entra ID deprovisioning lag is a known operational issue: deactivation in Entra does not always propagate to Brex immediately, leaving a window where a departing employee's card may remain technically active. For environments where this gap is a compliance concern, supplementing SCIM with direct API deactivation calls (PUT status=INACTIVE) provides a more reliable offboarding guarantee.