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.
`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.
`offers:read`	List or read studio offers and read their redemption history.
`offers:write`	Create, revise, activate, schedule, pause, resume, or revoke a studio offer.
`offers:apply`	Select and apply a studio offer when creating, preparing, or recovering a checkout link. Requires the matching checkout-link and `print_orders` scopes too.
`margins:read`	Preview an offer’s estimated margin using server catalog and cost evidence.
`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. Studio offer management also enforces studio roles: owners and admins can change offers, while authorized staff can read them. offers:write does not implicitly grant offers:read. Checkout-link creation, preparation, and recovery require offers:apply because those operations resolve the selected or automatic offer; see Studio discounts and offers. 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. 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.

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