Authentication

Stateful API requests authenticate with a bearer token:

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. Create, view, and revoke API keys from:

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.
`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.
`semantic_fields:read`	Read the platform semantic-field vocabulary.

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.

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.

{
  "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.

Start

Core Concepts

Product reference

Scopes

Missing or invalid credentials

Revocation

Test and Live keys

​Scopes

​Missing or invalid credentials

​Revocation

​Test and Live keys

Scopes

Missing or invalid credentials

Revocation

Test and Live keys