BrandRNA

brandRNA exposes two authentication surfaces:

REST API uses long-lived bearer keys (bd_*). Best for backend services, scripts, build pipelines, and traditional integrations.
MCP server uses OAuth 2.1 with PKCE and Dynamic Client Registration. Best for AI clients (Claude Desktop, Cursor, Lovable, v0, Bolt, custom agents) that need per-user delegated access.

Pick the surface that matches your client; never mix the two.

REST authentication

Every REST request must include a bearer token in the Authorization header:

curl -H "Authorization: Bearer $BRANDRNA_API_KEY" \
     https://api.brandrna.com/api/v1/pack/stripe.com

API keys are 32+ characters, prefixed with bd_, and use the URL-safe alphabet [A-Za-z0-9_-]. Server-side they are stored as a salted SHA-256 hash — we never persist plaintext, and there is no endpoint to re-fetch a key after the dashboard reveal-once modal.

Where to get an API key

Sign up at brandrna.com/signup and your first key is auto-minted. Open the API Keys dashboard and click Copy on the masked-prefix row at the top of the table.

If you've never run a brandRNA call, follow the Quickstart — it takes under 90 seconds.

Key lifecycle

Action	What happens	Cache propagation
Mint	Dashboard generates a new `bd_*` key, hashes it, returns plaintext once.	Immediate.
Label	Attach a friendly label (e.g. `production`, `mcp-claude-desktop`) for usage attribution.	Immediate.
Revoke	Hash row marked `revoked=true`. All in-flight tokens fail validation.	<60s (auth cache TTL).
Rotate	Atomic mint + revoke pair. New key issued before old is revoked — zero auth gap if you cut over within ~5 min.	<60s.

The /api/v1/usage endpoint returns per-key counters so you can spot unused or compromised keys before rotating. See Rate Limits for quota mechanics.

MCP authentication

MCP clients never send a bd_* key. They authenticate with OAuth 2.1

PKCE, where the brandRNA MCP server is the OAuth provider and the client (Claude Desktop, Cursor, etc.) registers itself dynamically via DCR.

MCP clients (Claude Desktop, Cursor, Lovable, v0, Bolt) authenticate via OAuth 2.1, not bearer keys. See the OAuth dance explainer for the full handshake and per-client setup.

The OAuth flow exchanges a one-time authorization code for an access token that is bound to the user's brandRNA account. Behind the scenes that token is converted into a managed key for the user, so usage and billing roll up to the same account as the REST surface.

If you're building a custom MCP client (i.e. not one of the five named clients above), see Wire an MCP-aware AI agent for an end-to-end walkthrough.

Security best practices

Always read keys from environment variables, never hard-code.
- Node/TS: process.env.BRANDRNA_API_KEY
- Python: os.environ['BRANDRNA_API_KEY']
- Shell: Authorization: Bearer $BRANDRNA_API_KEY
Never commit .env files, dashboard screenshots, or test fixtures containing real keys. The no-plaintext-keys guard blocks them in our docs build; mirror that protection in your CI.
Rotate on suspicion. Bad commit, leaked log, departing employee — rotate immediately and let the new key propagate (within ~60s).
Use labels to compartmentalise. One key per environment per service; revoke a single key without touching the rest.
Treat the reveal-once modal as authoritative. There is no re-fetch endpoint by design. If you miss the copy, mint a fresh key rather than fishing through logs.

If you spot a bd_* key in your own logs, error trackers, or client-side bundles, rotate it. Production-grade pipelines fan keys out via secret managers (Doppler, Vault, GCP Secret Manager) — never via plaintext config files committed to source control.

What's next

Learn the error shape so your client can surface auth failures cleanly.
Read the rate-limit contract — the same limiter applies to authenticated REST traffic.
If you're new, do the Quickstart first; it takes under 90 seconds.

Authentication