> ## Documentation Index
> Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Use an anonymous Test Mode session or a scoped API key to authenticate v1 API requests.

Stateful API requests authenticate with a bearer token:

```http theme={null}
Authorization: Bearer br_test_your_test_key
```

Batch Relay accepts three public bearer modes:

| Credential | Environment | Use |
| - | - | - |
| `br_anon_...` | Test Mode only | Keyless evaluation and first agent or CLI use. |
| `br_test_...` | Test Mode only | Persistent development, CI, and account-owned sandbox records. |
| `br_...` | Live Mode | Billable production work. |

Create an isolated anonymous session without signup at
`POST /v1/anonymous-sessions`, or let the CLI create and store one automatically.
See [Keyless Test Mode](/keyless-test-mode).

Create, view, and revoke API keys from:

```text theme={null}
https://app.batchrelay.com/developers
```

## Scopes

| Scope | Purpose |
| - | - |
| `print_orders:write` | Create print orders. |
| `print_orders:read` | Read print-order status. |
| `usage:read` | Read usage summary. |
| `webhooks:read` | Read webhook configuration. |
| `webhooks:write` | Create or change webhook configuration. |
| `studios:read` | List studios available to the credential. |
| `events:read` | Read event metadata for an authorized studio. |
| `events.orders.buyer.read` | Retrieve storefront purchaser name and email from a retained event. Requires an explicit active Studio integration opt-in and matching ownership or Studio grant. Anonymous keys are excluded. |
| `forms:read` | Read reusable form definitions and event form revisions. |
| `forms:write` | Create and update draft event form revisions. |
| `forms:publish` | Publish a draft event form revision. |
| `event_teams:write` | Prepare and apply an authorized bulk event-team change. |
| `studio_assets:read` | Read a studio asset-session or managed-asset lifecycle record. |
| `studio_assets:write` | Reserve, upload, finalize, cancel, or use studio assets for authorized event-image import work. |
| `studio_catalog:read` | Read a studio's products and packages. |
| `studio_catalog:write` | Create or change server-owned product and package drafts. |
| `studio_catalog:publish` | Publish studio catalog changes. |
| `storefronts:read` | Read the current published storefront assortment. |
| `storefronts:write` | Atomically replace a studio's published storefront assortment. |
| `checkout_links:read` | Read lifecycle metadata for a studio checkout link. |
| `checkout_links:write` | Create or revoke a studio checkout link. Requires the matching `print_orders` scope too. |
| `sandbox_promotions:read` | Create and review a bounded sandbox-to-Live promotion plan. Requires a Live API key. |
| `sandbox_promotions:apply` | Apply or roll back a reviewed sandbox promotion. Requires a Live API key. |
| `semantic_fields:read` | Read the semantic-field vocabulary when granted; the current public catalog endpoint does not require a bearer token. |

Studio management always uses an explicit studio ID in the request path. A
studio-owned key can access only its owning studio. An individual key must have
an active grant for the requested studio, and both the key and grant must carry
the required scope.

Anonymous credentials cannot access studio management. Test keys may read
studio management resources, but only Live Mode keys can create, update, or
publish form revisions, change studio catalog drafts, or replace storefront
assortments.

Checkout-link management is an isolated exception for Test Mode: only an
account-owned key beginning with `br_test_` can select its sandbox management
lane. Anonymous sessions cannot create, read, or revoke checkout links. The
credential record, not an `environment` field in the request, chooses the
lane; Test Mode has no implicit promotion into Live Mode.

Sandbox promotions are different. They require a Live `br_...` API key plus an
authorized studio grant and the matching `sandbox_promotions` scope. Test keys,
anonymous sessions, and OAuth sessions cannot promote studio configuration.
See [Promote sandbox studio setup](/sandbox-promotions).

Semantic-field vocabulary reads are public and do not require a bearer token:
`GET /v1/catalog/semantic-fields`.

## Missing or invalid credentials

The hosted API returns `401 invalid_api_key` for an invalid API key and `401
invalid_anonymous_session` for an invalid, revoked, or expired anonymous
session. A missing bearer credential on a stateful route returns
`invalid_api_key`; create an anonymous session first or use the CLI bootstrap.

```json theme={null}
{
  "code": "invalid_api_key",
  "message": "A valid Batch Relay API key is required.",
  "error": "A valid Batch Relay API key is required.",
  "docs_url": "https://docs.batchrelay.com/errors#invalid_api_key",
  "request_id": "req..."
}
```

## Revocation

Revoked keys stop working immediately. Create a new key if a bearer token is exposed.

Anonymous sessions expire after seven days by default and cannot be renewed.
Create a new session after expiry. Treat `br_anon_...` exactly like another
secret while it is active.

## Test and Live keys

Send Test and Live API keys to `https://api.batchrelay.com`. The stored API-key
record selects Test Mode or Live Mode and is authoritative. The `br_test_`
prefix helps identify a Test key, but does not choose the lane by itself.

Never put Live API keys or production provider credentials in test,
development, local test, or client configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.