Authentication & API keys

Every BatchRouter API request is authenticated with a secret API key sent as a bearer token. This page shows the key format, the two ways to create a key, how to verify your account, and how to rotate keys safely.

The Authorization headerCopy Anchor Link

Send your key in the Authorization header on every request to /v1 endpoints:

Authorization: Bearer br_live_xxxxxxxxxxxxxxxxxxxxxxxx

New production keys are prefixed br_live_. Legacy ob_live_ keys remain valid while active, so you don't need to migrate existing integrations immediately.

Base URLsCopy Anchor Link

Point your requests at the right environment. Keys are scoped per environment — a production key works against production only.

All public endpoints live under /v1 — for example https://api.batchrouter.com/v1/auth/account.

Create an API keyCopy Anchor Link

You can create a key two ways: from the dashboard (or its API) for an existing org, or with a single agent-first call that needs no email. In both cases the key value is shown only once — store it immediately in your secret manager.

From the dashboardCopy Anchor Link

If you have a BatchRouter account, create and name keys in the dashboard, or call the API while authenticated:

curl https://api.batchrouter.com/v1/auth/account/api-keys \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-worker",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Both name and expires_at are optional. Omit expires_at for a non-expiring key. The response returns the secret once:

{
  "api_key": "br_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "api_key_id": "key_abc123",
  "name": "production-worker",
  "expires_at": "2027-01-01T00:00:00Z"
}

Agent-first: register with no emailCopy Anchor Link

For automated onboarding and AI agents, POST /v1/auth/agent-register creates an org and issues an API key in a single unauthenticated call — no email or verification step. All body fields are optional.

curl https://api.batchrouter.com/v1/auth/agent-register \
  -H "Content-Type: application/json" \
  -d '{
    "org_name": "Acme Batch Jobs",
    "agent_name": "ingest-pipeline"
  }'

The response gives you your new org ID and the key (shown once):

{
  "org_id": "org_abc123",
  "api_key": "br_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "api_key_id": "key_def456"
}

Make an authenticated requestCopy Anchor Link

Once you have a key, verify it by fetching your account. GET /v1/auth/account returns your org, plan, credit balance, and members — a quick way to confirm the key works.

curl https://api.batchrouter.com/v1/auth/account \
  -H "Authorization: Bearer $BATCHROUTER_API_KEY"

A successful call returns your org details and current credit balance:

{
  "org_id": "org_abc123",
  "display_name": "Acme Batch Jobs",
  "plan": "free",
  "credit_balance": { "currency": "usd", "amount": "42.00" },
  "members": []
}

Check credit_balance before submitting work — if it's at zero, batch creation returns 402.

Rotate and revoke keysCopy Anchor Link

Keys never need to be rotated on a fixed schedule, but rotate promptly if a key may have leaked. Create the replacement first so there's no downtime, then revoke the old one.

Revoked and expired keys immediately return 401 on every request. To set an expiry up front, pass expires_at when you create the key; omit it for a non-expiring key.

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link