> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/brex.md).

# Brex

Connect Brex to sync card charges, refunds and Bill Pay invoices as bills, scoped to the spend you choose

Connecting Brex brings your settled Brex spend into Harmony as bills: card charges, refunds and Bill Pay invoices appear in the **Bills** view of the Contracts page, where you can link each one to the contract it pays for.

***

#### Prerequisites

1. **A Brex account admin or card admin** to create the API token. The token sees what its user can see, so use an account that can view the whole company's expenses.
2. **A Harmony account** with admin privileges.

***

#### Step 1: Create an API token in Brex

1. Sign in to [dashboard.brex.com](https://dashboard.brex.com/) and go to **Settings** > **Developer**
2. The first time, Brex asks you to accept the developer terms and conditions. Check **I accept and agree to the terms and conditions** and click **Submit**
3. Click **Create token** and enter a **Token name**, for example `Harmony`
4. Under **Scopes**, set these to **Read only** and leave everything else on **None**:

| Section  | Scope         | Why Harmony needs it                                                            |
| -------- | ------------- | ------------------------------------------------------------------------------- |
| Expenses | Card Expenses | The expenses themselves (card charges, refunds and Bill Pay) and their receipts |
| Payments | Vendors       | Vendor names for Bill Pay invoices                                              |
| Team     | Companies     | Identifies your Brex company, so the same company isn't connected twice         |
| Team     | Users         | Who paid for each card charge                                                   |
| Team     | Cards         | The name of the card used                                                       |
| Team     | Departments   | The department on each bill                                                     |

5. Confirm the scopes on the next screen with **Allow Access**
6. Copy the token (it starts with `bxt_`). Brex shows it only once

***

#### Step 2: Connect in Harmony

1. Log in to Harmony and go to **Settings** > **Integrations**
2. Find **Brex** under **SaaS Procurement** (or search for it) and click its card
3. Paste the token into **API token**
4. Choose what to sync. Both are on by default:
   * **Sync card charges**: card charges and their refunds
   * **Sync Bill Pay**: vendor invoices paid through Brex Bill Pay
5. Optionally, limit the sync with **Included GL accounts** and **Included Brex categories** (see below)
6. Click **Connect**

Harmony checks the connection right away: it confirms the token with Brex, checks that every scope above is granted, and validates your settings. If anything is missing, the save fails with a message naming the fix. The first bills appear within a day.

***

#### Integration settings

An expense syncs only if it matches every setting you fill in. An empty filter is off.

| Setting                      | What it does                                                                                                                                                                                              |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API token**                | The token from Step 1                                                                                                                                                                                     |
| **Sync card charges**        | Include card charges and their refunds                                                                                                                                                                    |
| **Sync Bill Pay**            | Include Bill Pay invoices                                                                                                                                                                                 |
| **Included GL accounts**     | Comma-separated GL account numbers. Keeps only expenses booked to an account that starts with one of them: `6400` covers every `6400xx` account. A Bill Pay invoice is kept when any of its lines matches |
| **Included Brex categories** | Comma-separated Brex expense categories, for example `RECURRING_SOFTWARE_AND_SAAS, SERVERS`. Keeps only expenses in one of them                                                                           |
| **Allow actions in Brex**    | Lets Harmony workflows make changes in Brex. Off by default. See [Allow actions in Brex](#allow-actions-in-brex)                                                                                          |

At least one of **Sync card charges** and **Sync Bill Pay** must be on.

{% hint style="info" %}
**GL accounts** exist in Brex only when Brex is connected to your accounting system. When they do, they are the most precise way to keep the sync to software spend: if every software account starts with `6400`, enter `6400`. Ask your finance team which accounts mean software.

**Categories** are on every Brex expense, but Brex files every Bill Pay invoice under `OTHER_BUSINESS_EXPENSES`, so listing only software categories leaves Bill Pay out.
{% endhint %}

You can change the settings at any time from the Brex card. They apply from the next daily sync.

***

#### Allow actions in Brex

The sync only reads from Brex. Turn on **Allow actions in Brex** to also let Harmony workflows make changes there: create, lock, unlock and terminate cards, update users and spend limits, and write expense memos. It's off by default, and the sync works the same with it off.

**Token scopes**

Actions need a token with more access than the sync. Create a new token (Step 1) with these scopes:

| Section  | Scope         | Access             | Why Harmony needs it                                                       |
| -------- | ------------- | ------------------ | -------------------------------------------------------------------------- |
| Team     | Users         | **Read and write** | Update, invite and deactivate users                                        |
| Team     | Cards         | **Read and write** | Create, lock, unlock and terminate cards, and change a vendor card's limit |
| Budgets  | Budgets       | **Read and write** | Read and change spend limits, and add or remove their members              |
| Expenses | Card Expenses | **Read and write** | Write an expense's memo                                                    |
| Team     | Titles        | Read only          | Find a title by name when updating a user                                  |
| Team     | Locations     | Read only          | Find a location by name when updating a user                               |
| Team     | Cost Centers  | Read only          | Find a cost center by name when updating a user                            |
| Team     | Companies     | Read only          | As for the sync                                                            |
| Team     | Departments   | Read only          | As for the sync                                                            |
| Payments | Vendors       | Read only          | As for the sync                                                            |

{% hint style="info" %}
On Brex Empower, creating cards through the API also needs **budget management** on your Brex plan. Without it, Brex refuses to create cards even with the right scopes.
{% endhint %}

**Turn it on**

1. Go to **Settings** > **Integrations**, find **Brex** and click its card
2. Next to **API token**, click **Replace** and paste the new token
3. Turn on **Allow actions in Brex** and click **Save changes**

Saving checks that the token can read Titles, Locations, Cost Centers and Budgets, and names any it can't. Brex doesn't say whether a token can **write**, so saving can't check that. Use **Test & check** for it.

**Test & check**

Once the switch is saved on, **Test & check** appears under it. Click it, then **Run test**. Harmony uses the saved token to try the changes that can be undone or change nothing, as the Brex user who created the token:

* **Update users**: saves that user without changing anything
* **Create a card**: creates a $1 virtual card for that user
* **Terminate a card**: terminates the test card right away. Brex notifies the user, and the card stays in their card list as terminated
* **Remove the card's budget**: on Brex Empower, Brex creates a budget for every new card. Harmony archives the test card's budget

Each action shows as passed, failed or not tested, with the reason. Changing spend limits and writing expense memos can only be tried on real ones, so they show as not tested.

***

#### Disconnect Brex

1. Go to **Settings** > **Integrations**
2. Find **Brex** and click its card
3. Click **Disconnect** and confirm

Harmony stops syncing from Brex. Bills already synced stay in Harmony.

***

#### Troubleshooting

**"Brex rejected this token"** The token wasn't copied in full or was deleted in Brex. Create a new token (Step 1) and paste it again.

**"This Brex token cannot read …"** The token is missing one of the scopes in Step 1, and the message names which. Create a new token with all six set to **Read only**.

**"Include card charges, Bill Pay, or both"** **Sync card charges** and **Sync Bill Pay** are both off. Turn on at least one.

**"Enter a comma-separated list of GL account numbers"** **Included GL accounts** holds something other than account numbers. Enter only the numbers, for example `6400, 6500`.

**"These are not Brex categories: …"** A category is misspelled. Use Brex's category names, for example `RECURRING_SOFTWARE_AND_SAAS`.

**"This Brex company is already connected as '…'"** Another Brex connection in your Harmony account already syncs this Brex company. Use that one, or disconnect it first.

**"This Brex token cannot read titles.readonly, …" after turning on Allow actions in Brex** The token is missing a scope that actions need. Create a new token with the scopes in [Token scopes](#token-scopes) and replace it.

**Test & check: "The token can't change users"** The token has **Users** set to **Read only**. Create a new token with **Users** set to **Read and write** and replace it.

**Test & check: "Brex refused to create a card"** Either the token doesn't have **Cards** set to **Read and write**, or your Brex plan doesn't include budget management, which Brex Empower needs to create cards through the API.

**Test & check: "Couldn't terminate the test card ending in …"** Terminate the card in Brex. It's limited to $1 and locks itself after a day anyway.

**Test & check: "Couldn't remove the budget Brex created for the test card"** Archive the "Harmony connection test" budget in Brex. If the message asks for Budgets access, create a new token with **Budgets** set to **Read and write**.

**Test & check: "A test card may have been created"** Harmony couldn't confirm how the test ended. Check the card list in Brex for a "Harmony connection test" card before running the test again.

**"Could not reach Brex" or "Brex is rate limiting requests"** A temporary error on Brex's side. Try again in a minute.

**No bills appear after setting GL accounts** Check that your expenses show a **GL Account** in Brex. Without Brex connected to your accounting system there are none, so a GL filter matches nothing. Check the numbers with your finance team, or clear the filter.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/saas-applications/brex.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
