Skip to main content

​
About Brex

Brex is a corporate card and spend-management platform. Serval’s Brex integration connects with a single Brex user API token and covers nine areas of the Brex platform - team, expenses, budgets, transactions, payments, accounting, travel, custom fields, and onboarding - so your workflows can read and update Brex data whenever they run. Everything happens live against Brex; there is nothing to import or schedule. Authentication: Brex user API token, pasted into Serval and sent as a secure bearer credential on every request. There is no OAuth sign-in flow. Data sync: On demand only. Serval contacts Brex exclusively when a workflow step runs - there is no background sync, no polling schedule, and no webhooks from Brex.

​
What the Brex integration enables

Anything defined in the Brex API can be accessed through Serval.

​
Get your credentials

Serval connects to Brex with a user API token that you generate in the Brex dashboard. The token’s enabled permission scopes determine exactly what Serval can read or write - nothing more. See the Brex authentication documentation for background, or the Brex Developer Portal for the full platform reference.
1

Sign in to Brex

Open the Brex Dashboard and sign in.
2

Open the developer settings

Navigate to Developer > Settings in the Brex dashboard - the developer settings page.
3

Create a token

Click Create Token and enter a descriptive name, for example “Serval Integration”.
4

Select permission scopes

Choose the scopes your workflows need. At minimum, grant read access for Users, Cards, Card Accounts, and Departments - these four are required for Serval’s connection health checks to pass.
5

Allow access and copy the token

Click Allow Access, then copy the token right away and keep it somewhere safe until you paste it into Serval.
Brex shows the token only once, at creation time. If you navigate away without copying it, you will need to create a new token.
Grant write scopes only if your workflows will create or modify Brex data (for example, creating budgets or locking cards). Read-only scopes are enough for reporting and lookup workflows.

​
Connect in Serval

1

Add the Brex integration

In Serval, add a new connection and choose Brex.
2

Paste your token

Paste the token into the API Token field. It is the only field, it is required (marked with an asterisk), and it hides what you type like a password. The helper text under the field reads “Generate a user token from your Brex dashboard at Developer > Settings”. Paste carefully: the form does not check the token when you submit, so even a blank or mistyped value saves successfully.
3

Save the connection

Save the form. If saving fails, you may see “Failed to install integration” or “Failed to save configuration. Please try again.”
4

Run the health checks

Run the connection health checks immediately after saving (see below). Serval does not test the token against Brex when you save - any value is accepted - so the health checks are your first real confirmation that the token works.
When you reopen the connection settings later, the saved token appears as a masked value (bullet characters plus its last 4 characters) with a control to replace it - a Replace button or a pencil icon, depending on where you edit. Clicking it opens a password input with the placeholder “Enter new value”. Any time you save this connection’s settings again - whether you are rotating the token or just re-saving the form - use that control and paste the complete token before saving. Do not save with the field blank or with only the masked value showing. If an update fails, Serval shows an error starting with “Failed to update integration:” or the message “Failed to update configuration”.

​
Verifying the connection

The Brex integration ships four health checks. Run them right after connecting and after any edit to the connection. List Brex Users - confirms the token is valid and can list the users in your Brex account.
  • Success: “Successfully listed users from Brex (sample size: [number])”
  • Failure: “Unable to list users from Brex. Please verify your API token is valid and has the ‘users.read’ scope enabled.”
List Brex Cards - confirms the token can list cards.
  • Success: “Successfully listed cards from Brex (sample size: [number])”
  • Failure: “Unable to list cards from Brex. Please verify your API token has the ‘cards.read’ scope enabled.”
List Brex Card Accounts - confirms the token can list card accounts.
  • Success: “Successfully listed card accounts from Brex (count: [number])”
  • Failure: “Unable to list card accounts from Brex. Please verify your API token has the ‘accounts.card.read’ scope enabled.”
List Brex Departments - confirms the token can list departments.
  • Success: “Successfully listed departments from Brex (sample size: [number])”
  • Failure: “Unable to list departments from Brex. Please verify your API token has the ‘departments.read’ scope enabled.”
Each check needs its own Brex scope, so a mix of green and red checks means the token is valid but missing specific scopes - not that the connection is broken. Likewise, all four checks can pass and a workflow can still fail if it touches an area the checks do not cover (for example, expenses or budgets). Grant the missing scope in the Brex dashboard; if that means creating a new token, update the connection in Serval and paste the complete new token.

​
Gotchas and troubleshooting

The token appears masked when you open the connection settings. Saving the form without replacing the masked value with the complete token can leave the connection without a working credential, and workflows will start failing. Whenever you edit this connection for any reason, click the replace control, paste the entire token (or the new one, if rotating), save, and confirm all four health checks pass.
Serval accepts whatever you paste at install time - a typo, a truncated paste, an already-revoked token, or even an empty field will all save successfully. The problem only surfaces when the health checks run or a workflow calls Brex. Always run the health checks immediately after connecting.
Access is exactly the token’s enabled Brex scopes, evaluated per area. A token can pass the users check yet fail the cards check, or pass all four health checks yet fail on an expenses workflow. If a workflow gets permission errors from Brex, grant the relevant scope in the Brex dashboard; if you create a new token to do it, update the connection in Serval with the full new token.
Brex list results are paginated with a cursor: each response includes a batch of items plus a pointer to the next page. A single workflow step returns only one page, so workflows that need everything must loop and follow the next-page cursor until there are no more pages. If a workflow seems to be “missing” records, pagination is the usual cause.
Serval attaches your token exclusively to requests bound for Brex’s official API hosts: platform.brexapis.com and its secure companion host, secure-platform.brexapis.com (the host Brex uses for PCI-sensitive card-number retrieval). The integration’s built-in actions all target Brex’s main API host; requests to any other destination never receive the credential.
Need help? Contact support@serval.com for assistance with your Brex integration.