A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Brex API is how an app or AI agent works with a company's Brex account: reading settled card and cash transactions, checking account balances, issuing and locking cards, sending transfers to vendors, and managing expenses and receipts. Access is granted through a Bearer token, either a user API token or an OAuth grant, and the scopes on that token set which resources a call can read or write, with a user's Brex role narrowing it further in places. Brex can deliver an event to a registered endpoint when something changes, like a transfer completing or an expense payment updating.
How an app or AI agent connects to Brex determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Brex tools to agents, and each is governed by the token behind it and the scopes that token carries.
The REST API accepts and returns JSON over HTTPS and pages through lists with a cursor, at https://platform.brexapis.com. Newer https://api.brex.com hostnames are also supported, with legacy hostnames maintained. A call authenticates with a Bearer token, either an OAuth access token or a user-generated API token. Resources are versioned in the path, with v1 and v2 living side by side.
A first-party hosted Model Context Protocol server at https://api.brex.com/mcp exposes Brex tools to AI agents and MCP-compatible clients. It is in beta, so its tools may change. It authenticates with OAuth, where supporting clients start a browser-based flow and Dynamic Client Registration removes pre-registration, or with a Brex API token sent as a Bearer token. It exposes tools across expenses, cards, banking accounts and transactions, users and org data, and vendors and bills. A user reaches only the tools their Brex role allows, and actions like approvals and card management are not yet available.
Brex POSTs events to an HTTPS endpoint registered through the Webhooks API. The receiver validates the Webhook-Signature header against the endpoint's signing secrets, retrieved from the webhook secrets endpoint. Multiple signatures can appear during key rotation, so a receiver validates against all current keys.
OAuth uses the standard authorization-code flow, where a user grants a partner application access to their Brex account and consents to a set of scopes. The resulting access token represents that user and lasts one hour, after which it is refreshed. This is the route for an application acting on behalf of accounts it does not own.
A user token is generated in the Brex dashboard's developer settings and authenticates the account that created it. Scopes are chosen when the token is created, so a token can be limited to just the access an integration needs. A user token expires after 90 days of inactivity but persists with regular use.
The Brex API is split into areas an agent can act on, like card and cash transactions, accounts, cards, users, budgets and spend limits, vendors, transfers, and expenses. Each area has its own methods, and writes in some areas move real money or change who can spend.
Methods for reading settled card and cash transactions.
Methods for reading card and cash accounts, balances, and statements.
Methods for creating and managing physical and virtual cards.
Methods for managing users and their spend limits.
Methods for creating and managing budgets and spend limits.
Methods for managing the vendors that payments are sent to.
Methods for creating and reading transfers between accounts and to vendors.
Methods for reading and updating expenses and their receipts.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
TransactionsMethods for reading settled card and cash transactions.2 | ||||||
| GET | /v2/transactions/card/primary | List settled transactions for the primary card account. | read | transactions.card.readonly | Current | |
Read-only. Only settled transactions are returned, pending ones are not. Acts oncard_transaction Permission (capability) transactions.card.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/transactions/cash/{id} | List transactions for a specific cash account. | read | transactions.cash.readonly | Current | |
Read-only. Acts oncash_transaction Permission (capability) transactions.cash.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsMethods for reading card and cash accounts, balances, and statements.5 | ||||||
| GET | /v2/accounts/card | List all card-type accounts. | read | transactions.card.readonly | Current | |
Read-only. Acts oncard_account Permission (capability) transactions.card.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts/card/primary/statements | List finalized statements for the primary card account. | read | transactions.card.readonly | Current | |
Read-only; returns finalized statements only. Acts onstatement Permission (capability) transactions.card.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts/cash | List all cash accounts with their status and balance. | read | accounts.cash.readonly | Current | |
Read-only; the response includes current account balances. Acts oncash_account Permission (capability) accounts.cash.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts/cash/primary | Retrieve the primary cash account and its status. | read | accounts.cash.readonly | Current | |
Read-only. Acts oncash_account Permission (capability) accounts.cash.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts/cash/{id} | Retrieve a specific cash account by ID with its status. | read | accounts.cash.readonly | Current | |
Read-only. Acts oncash_account Permission (capability) accounts.cash.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CardsMethods for creating and managing physical and virtual cards.7 | ||||||
| GET | /v2/cards | List all cards, filterable by user. | read | cards.readonly | Current | |
Read-only. The cards scope without .readonly grants write. Acts oncard Permission (capability) cards.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/cards | Create a new card. | write | cards | Current | |
Issues a real spending card. Limited to 5,000 cards created per account per 24 hours. Acts oncard Permission (capability) cardsVersionAvailable since the API’s base version Webhook eventNone Rate limit5,000 per 24 hours per account SourceOfficial documentation ↗ | ||||||
| GET | /v2/cards/{id} | Retrieve a card by ID. | read | cards.readonly | Current | |
Read-only. Acts oncard Permission (capability) cards.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/cards/{id} | Update an existing card. | write | cards | Current | |
Changes card settings such as spend controls. Acts oncard Permission (capability) cardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/cards/{id}/pan | Retrieve a card's number, CVV, and expiration date. | read | cards.readonly | Current | |
Returns the full card number (PAN), CVV, and expiry; the response also includes the cardholder name. Acts oncard Permission (capability) cards.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/cards/{id}/lock | Lock an existing, unlocked card. | write | cards | Current | |
Temporarily stops the card from being used; reversible with unlock. Acts oncard Permission (capability) cardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/cards/{id}/terminate | Terminate an existing card. | write | cards | Current | |
Permanently cancels the card. Acts oncard Permission (capability) cardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Team (Users)Methods for managing users and their spend limits.4 | ||||||
| GET | /v2/users | List all users. | read | users.readonly | Current | |
Read-only. The users scope without .readonly grants write. Acts onuser Permission (capability) users.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users | Invite a new user as an employee. | write | users | Current | |
Adds a person to the company on Brex. Acts onuser Permission (capability) usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/{id} | Retrieve a user by ID. | read | users.readonly | Current | |
Read-only. GET /v2/users/me returns the user tied to the access token. Acts onuser Permission (capability) users.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users/{id}/limit | Set the monthly spend limit for a user. | write | users | Current | |
Changes how much a person can spend each month. Acts onuser_limit Permission (capability) usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Budgets & Spend LimitsMethods for creating and managing budgets and spend limits.4 | ||||||
| GET | /v2/budgets | List budgets. | read | budgets | Current | |
Budgets v2 supersedes the deprecated v1 budgets resource. Acts onbudget Permission (capability) budgetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/budgets | Create a budget. | write | budgets | Current | |
Defines a new spending budget for the company. Acts onbudget Permission (capability) budgetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/spend_limits | List spend limits. | read | budgets | Current | |
A spend limit caps spending for a person, team, or category. Acts onspend_limit Permission (capability) budgetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/spend_limits | Create a spend limit. | write | budgets | Current | |
Sets a new ceiling on company spending. Acts onspend_limit Permission (capability) budgetsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
VendorsMethods for managing the vendors that payments are sent to.3 | ||||||
| GET | /v1/vendors | List all vendors for an account. | read | vendors | Current | |
The vendors scope covers both reading and writing vendor records. Acts onvendor Permission (capability) vendorsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/vendors | Create a new vendor. | write | vendors | Current | |
Adds a payee that transfers can be sent to. Vendors are account-specific. Acts onvendor Permission (capability) vendorsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/vendors/{id} | Delete a vendor by ID. | write | vendors | Current | |
Removes a payee record. Acts onvendor Permission (capability) vendorsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payments & TransfersMethods for creating and reading transfers between accounts and to vendors.3 | ||||||
| GET | /v1/transfers | List existing transfers for an account. | read | transfers | Current | |
Lists ACH, wire, or check payments made to vendors. Acts ontransfer Permission (capability) transfersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/transfers | Create a new transfer by ACH, wire, or check. | write | transfers | Current | |
Moves real money. Limited to 1,000 transfers and 100 international wires per account per 24 hours. Acts ontransfer Permission (capability) transfersVersionAvailable since the API’s base version Webhook event transferProcessedRate limit1,000 transfers / 100 intl wires per 24 hours per account SourceOfficial documentation ↗ | ||||||
| GET | /v1/transfers/{id} | Retrieve a transfer by ID. | read | transfers | Current | |
Read-only. Acts ontransfer Permission (capability) transfersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ExpensesMethods for reading and updating expenses and their receipts.5 | ||||||
| GET | /v1/expenses | List expenses under the account. | read | expenses.card.readonly | Current | |
Admins and bookkeepers see all expenses; regular users see only their own. Acts onexpense Permission (capability) expenses.card.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/expenses/{id} | Retrieve a specific expense by ID. | read | expenses.card.readonly | Current | |
Read-only. Acts onexpense Permission (capability) expenses.card.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/expenses/card/{expense_id} | Update a card expense. | write | expenses.card | Current | |
Admins and bookkeepers can edit any expense; regular users only their own. Acts onexpense Permission (capability) expenses.cardVersionAvailable since the API’s base version Webhook event expensePaymentUpdatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/expenses/card/{expense_id}/receipt_upload | Create a new receipt upload for a card expense. | write | expenses.card | Current | |
Returns a pre-signed upload URL that expires in 30 minutes. Acts onreceipt Permission (capability) expenses.cardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/expenses/card/receipt_match | Upload a receipt and match it to an expense automatically. | write | expenses.card | Current | |
Returns a pre-signed upload URL that expires in 30 minutes; Brex matches the receipt to a transaction. Acts onreceipt Permission (capability) expenses.cardVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Brex can notify an app when something happens in an account, like a transfer completing or an expense payment updating. It sends an event to a registered endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
transferProcessed | A transfer was processed. An integration uses this to confirm that an outgoing payment completed. | /v1/transfers |
transferFailed | A transfer failed and the money did not move. | /v1/transfers |
expensePaymentUpdated | The payment state of an expense changed. | /v1/expenses/card/{expense_id} |
accountingRecordReadyForExport | An accounting record is ready to be exported to an accounting system. | In-app only |
userUpdated | A user record changed. | /v2/users/v2/users/{id}/limit |
referralCreated | A referral was created. | In-app only |
referralActivated | A referral was activated. | In-app only |
referralApplicationStatusChanged | The application status of a referral changed. | In-app only |
Brex caps how often an app can call, by a per-account request rate measured over a rolling window, with separate daily ceilings on money movement like transfers and wires.
Brex meters requests by rate, not by a per-method cost. An account is allowed up to 1,000 requests in any rolling 60-second window. Money movement has its own daily ceilings: up to 1,000 transfers and up to 100 international wires per 24 hours, and up to 5,000 cards created per 24 hours. Limits are enforced per Client ID and per Brex account, and Brex may reduce them further to prevent abuse. Going over returns HTTP 429, and the guidance is to retry with exponential backoff and jitter.
List endpoints are cursor-based: a limit parameter sets the page size and a cursor parameter fetches the next page. In February 2026 the maximum limit on the List Expenses endpoints was reduced from 1,000 to 100. Transactions appear only once settled, so pending activity is not returned and cannot be paged.
The maximum page size on the List Expenses endpoints is 100 items. A receipt upload or receipt-match call returns a pre-signed upload URL that expires in 30 minutes.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request was malformed or a parameter was invalid. | Check the request body and parameters against the reference, fix them, and resend. |
| 401 | unauthorized | No valid token was provided, or the token expired. An OAuth token lasts one hour and a user token expires after 90 days of inactivity. | Send a valid Bearer token, refreshing the OAuth token or reusing a still-active user token. |
| 403 | forbidden | The token is valid but lacks the scope or the Brex role needed for this request. | Request the scope the method needs when generating the token, and confirm the user's role allows the action. |
| 404 | not_found | The requested object does not exist or is not visible to this token. | Verify the object ID and confirm the token's account can see it. |
| 429 | too_many_requests | A rate limit was exceeded. Limits are enforced per Client ID and per Brex account. | Back off and retry with exponential backoff and some randomness to avoid a thundering herd. |
| 500 | internal_server_error | An error on Brex's side. Include the X-Brex-Trace-Id header value when contacting support. | Retry with backoff, and if it persists contact developer support with the trace ID. |
Brex versions its API by the path, with v1 and v2 resources living side by side, and ships dated changes through its developer changelog rather than a single account-wide version string.
Brex versions resources in the path rather than with an account-wide version string, so v1 and v2 resources are called side by side. Newer resources like Transactions, Team, Budgets, and Spend Limits sit under v2, while Payments, Vendors, Transfers, Expenses, and Webhooks remain under v1. Dated changes ship through the developer changelog.
The Card Expenses endpoints were deprecated in favor of the consolidated Expenses API, and the Fields API official documentation launched.
New transfer and vendor-management endpoints landed on the Payments API, and Budgets v2 was introduced while v1 was deprecated.
The Webhooks API launched in beta, letting an app subscribe to events instead of polling, and an X-Brex-Trace-Id header was introduced.
The Transactions API added endpoints for cash transactions and the primary card account.
Track the changelog, since v1 and v2 resources evolve independently.
Brex API changelog ↗Bollard AI sits between a team's AI agents and Brex. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.