Authentication

Overview

API keys allow external clients (mobile apps, scripts, server-to-server integrations) to access the REST API without browser-based session authentication.

Each API key is:

• User-scoped — actions are attributed to the user who created the key
• Organization-scoped — the key only has access to data within the organization it was created in
• Time-limited — keys have a required expiration date

Creating an API Key

1. Navigate to Settings in your organization dashboard
2. Select the API Keys tab
3. Click Create Key
4. Enter a descriptive name (e.g., "Mobile App", "CI/CD Pipeline")
5. Select an expiration period (30 days, 60 days, 90 days, 1 year, or custom)
6. Click Create

Using an API Key

Include the API key in the Authorization header of every request:

Authorization: Bearer ba_<your-api-key>

Token Format

API keys use the format ba_ followed by 40 hexadecimal characters:

ba_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9

The ba_ prefix enables automated secret scanning tools (e.g., GitHub, GitGuardian) to detect leaked keys.

Key Lifecycle

Revoking a Key

To revoke a key, go to Settings > API Keys and click Revoke next to the key. Revocation is immediate and irreversible.

Response Format

All successful responses follow this format:

{
  "data": { ... },
  "total": 42
}

• data: The resource or array of resources
• total: Total count (only in list endpoints, for pagination)

Data Formats

The REST API is deliberately not localized. The app's screens render dates and numbers in the reader's language and timezone (see Timezone); the API does the opposite, and returns the same bytes to every caller:

• Timestamps are ISO 8601 in UTC, always with the Z suffix — "2026-09-01T14:54:01.000Z". They are never shifted into the timezone on the key owner's profile, and never abbreviated or reordered by language. Convert to a local zone in your own client, at the point of display.
• Named date windows are cut in UTC. Where an endpoint accepts one — today, this-week, this-month, older — its boundaries sit at midnight UTC, never in a timezone read off a profile, so today is the current UTC day for every caller. The app's own lists cut the same windows at midnight in the reader's timezone (see Timezone), which means such a filter can return a different set of records here than the same user sees on screen. Check the endpoint's own reference page for whether it takes one.
• Numbers are raw JSON numbers — no grouping separators, no decimal comma, no currency symbol, no percent sign. Money is integer cents, so 480000 is $4,800.00.

The same holds for what you send. Dates in a request body are ISO 8601 — a plain day such as "2026-10-15" or a full timestamp — and numbers are unformatted, so "1.234,50" and "$1,234.50" are both rejected.

This contract will not change with the interface language of the user who owns the API key, or with any language added later.

Error Responses

Validation errors (422) include details:

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {
      "email": ["Invalid email address"]
    },
    "formErrors": []
  }
}

Security Best Practices

• Never commit API keys to source control
• Store keys in environment variables or a secrets manager
• Use short expiration periods when possible
• Revoke keys immediately if they may have been compromised
• Create separate keys for different applications or environments
• Monitor usage via the "Last Used" column in the API Keys settings