Authentication & Rate Limits

The Agent Provisioning API has two trust zones:

Surface	Auth	Who calls it
`POST /v1/agents:from-url`, `GET /v1/agents/builds/:id`, `…/events`	`brs_live_` API key	Your backend only
`POST /api/public/agents/:slug/*` (chat)	None (anonymous, slug-based)	The browser directly

API keys & scopes

brs_live_ keys are organization-scoped — the consumer brings its own Brainstormer org + key, and all provisioned agents and their cost bill to that org. Pass the key as a bearer token:

Authorization: Bearer brs_live_YOUR_KEY

Keys carry scopes. The provisioning endpoints require agents:write. A key missing the required scope is rejected by the gateway:

Scope	Grants
`agents:write`	Provision agents (`/v1/agents:from-url` + build status endpoints).
`chat`	Chat with agents (`/v1/chat`).
`kb:read`	Search knowledge bases (`/v1/kb/search`).

403 — missing scope

{
  "error": "insufficient_scope",
  "message": "This API key is missing the required \"agents:write\" scope."
}

Select a key’s scopes when you generate it in the Developer Portal (/developer → pick an application → Generate Key). New keys default to chat and kb:read; tick agents:write to allow provisioning. A key’s granted scopes are listed alongside it in the key table.

No secrets in the browser (READ FIRST)

A browser must never hold a brs_live_ key. Provisioning is a cost-incurring write (scrape + LLM + embeddings), so it is authorized by a secret your server controls — never shipped to end users.

The only supported v1 integration is Pattern A — client backend proxy:

Browser ──▶ Your backend ──(brs_live_ key)──▶ POST /v1/agents:from-url
Browser ◀── Your backend ◀── SSE relay / webhook
Browser ──────────────────────────────────▶ POST /api/public/agents/:slug/chat  (direct, no key)

The asymmetry that makes this safe: chat never needs a secret — it is the anonymous, slug-based surface, embeddable front-end-only. Only the provisioning write is gated, and that’s the part your backend handles. See the quickstart for a Next.js reference.

A publishable, origin-scoped browser session token (Pattern B) for backend-less consumers is deferred — not in v1.

Cloudflare Turnstile (bot protection)

from-url accepts a Cloudflare Turnstile token, verified server-side. When the platform is configured with a TURNSTILE_SECRET_KEY, the token is required.

Render the Turnstile widget in the browser; obtain a token per submit.
Relay the token to your backend.
Include it as turnstileToken on the from-url request body.

A missing or invalid token returns 400 turnstile_failed synchronously. (A later bot-check rejection inside the build surfaces as a failed event with error code turnstile_failed.)

Rate limits — `429` + `Retry-After`

from-url is rate-limited on two axes:

Limit	Default	Scope
Per-key	`api_keys.rate_limit_rpm` (60 rpm)	Your API key
Per-IP	10 requests / minute	The submitting IP (stricter)

Over-limit requests return 429 with a Retry-After header (in seconds). Back off and retry after that delay.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Backend — honor Retry-After

async function submitWithBackoff(body: object, attempt = 0): Promise<Response> {
  const res = await fetch("https://app.brainstormer.io/v1/agents:from-url", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BRAINSTORMER_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get("Retry-After") ?? 30) * 1000;
    await new Promise((r) => setTimeout(r, wait));
    return submitWithBackoff(body, attempt + 1);
  }
  return res;
}

Rate limits hit inside a running build (rather than on submit) surface as a failed event with error code rate_limited (retryable: true).

Idempotency

Send an Idempotency-Key header (a UUID you generate) on from-url so a double-submit — a retried network request, a double-clicked button — returns the same build instead of spawning a second one.

Idempotency-Key: 7f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d

Combined with handle dedup (a fresh existing published agent for the same normalized handle is reused and returned ready instantly), repeat submits are safe, fast, and free. See Build lifecycle.

Error reference

HTTP	Code	When
`400`	`unsupported_url`	URL isn’t a readable YouTube/Instagram channel.
`400`	`turnstile_failed`	Missing/invalid Turnstile token.
`401`	—	Missing or invalid `Authorization` header.
`403`	`insufficient_scope`	Key lacks `agents:write`.
`429`	`rate_limited`	Per-key or per-IP limit; honor `Retry-After`.

For the in-build error model (plan_limit, insufficient_credits, scrape_failed, …) with retryable semantics, see the ProvisioningErrorCode table.

Overview

Services

Architecture

Agent Provisioning API

Deployment

Design System (Neo)

Provisioning Auth & Rate Limits

Authentication & Rate Limits

API keys & scopes

No secrets in the browser (READ FIRST)

Cloudflare Turnstile (bot protection)

Rate limits — `429` + `Retry-After`

Idempotency

Error reference

​Authentication & Rate Limits

​API keys & scopes

​No secrets in the browser (READ FIRST)

​Cloudflare Turnstile (bot protection)

​Rate limits — 429 + Retry-After

​Idempotency

​Error reference

Authentication & Rate Limits

API keys & scopes

No secrets in the browser (READ FIRST)

Cloudflare Turnstile (bot protection)

Rate limits — `429` + `Retry-After`

Idempotency

Error reference