Getting Started with brex-app APIs

This guide walks you through setting up your brex-app workspace, generating scoped API credentials, handling secrets safely in production, and verifying everything works with a live API call. By the end you'll be ready to integrate corporate finance data into your application.

A workspace in brex-app is the top-level container for your organization — it holds your team members, accounts, cards, budgets, and API credentials. You'll need one before you can issue any API keys.

brex-app uses scoped bearer tokens — every key is bound to a specific set of permissions and an optional expiry date. You can generate keys via the dashboard UI (no code required) or programmatically through the REST API.

Option A — Dashboard UI

Option B — REST API (curl)

If you're bootstrapping a new environment in CI/CD or Terraform, you can create a key programmatically using an existing admin token. Replace $BREX_ADMIN_TOKEN with your workspace admin bearer token.

curl -X POST https://api.brex-app.com/v1/developer/keys 
  -H "Authorization: Bearer $BREX_ADMIN_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "my-first-key",
    "scopes": ["accounts:read", "transactions:read", "cards:write"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

A successful 201 Created response returns the new key with its plaintext token:

{
  "id": "key_01HN7QZPX4RJVK8MYWF3D9CSA",
  "name": "my-first-key",
  "token": "brex_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scopes": ["accounts:read", "transactions:read", "cards:write"],
  "created_at": "2024-06-01T12:00:00Z",
  "expires_at": "2025-12-31T23:59:59Z"
}

A leaked API key with payment or card-write scopes can cause real financial harm. These patterns protect your credentials in development and in production.

Local development — environment variables

# Add to your .env file (never commit this file)
BREX_API_KEY=brex_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Load in Node.js
const apiKey = process.env.BREX_API_KEY;

# Load in Python
const client = new SecretsManagerClient({ region: "us-east-1" });
const { SecretString } = await client.send(
  new GetSecretValueCommand({ SecretId: "prod/brex-app/api-key" })
);
const { BREX_API_KEY } = JSON.parse(SecretString);

Production — AWS Secrets Manager

For production workloads, store your brex-app key in a secrets manager rather than environment variables. AWS Secrets Manager provides automatic rotation, fine-grained IAM access control, and a full audit trail.

With your key stored in an environment variable, make a request to the GET /v1/accounts endpoint. This is a read-only call that lists all accounts in your workspace — a reliable smoke test since it requires only theaccounts:read scope.

curl -X GET https://api.brex-app.com/v1/accounts 
  -H "Authorization: Bearer $BREX_API_KEY" 
  -H "Accept: application/json"

If the key is valid and scoped correctly, you'll receive a paginated response like this:

{
  "data": [
    {
      "id": "acc_01HN7QZPX4ABC123DEF456",
      "name": "Operating Account",
      "currency": "USD",
      "balance": {
        "amount": 1250000,
        "currency": "USD"
      },
      "status": "active",
      "created_at": "2024-01-15T08:30:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}