Authentication

Quickstart

curl https://api.reelsbuilder.ai/api/v1/account/credits \
  -H "Authorization: Bearer rb_your_api_key_here"

Get a key

Sign in and visit the developer dashboard (or the API Settings tab on your dashboard). Click Generate API Key. The full plaintext key is shown exactly once — copy it immediately. After that, only the SHA-256 hash and a non-secret prefix (rb_xxxxxxxx…) are stored server-side.

Free accounts include fixed starter videos (free_classic_videos), not a 1,000-credit or 1,000-token grant. Dashboard plans pool Starter 10,000 / Pro 40,000 / Business 150,000 tokens monthly. Live API keys use prepaid USD, not those token pools. See pricing for plan limits.

Header format

Send the key in the Authorization header using the Bearer scheme:

Authorization: Bearer rb_your_api_key_here

The header name and scheme are case-insensitive, but the key itself is case-sensitive (it's base64url-encoded random bytes, not a passphrase).

Key shape

• Prefix: All production keys start with rb_. Sandbox keys start with rb_test_ and return fixtures without charging live credits.
• Length: 46 characters total (rb_ + 43 base64url chars). Reject anything under 20 chars locally — those are never valid.
• Entropy: 32 random bytes from crypto.randomBytes (256 bits). Not derived from a UUID, not derived from your account, not recoverable.
• Storage: Only the SHA-256 hash and an 8-character display prefix are persisted. The plaintext is never stored after creation.

Examples by language

cURL

curl https://api.reelsbuilder.ai/api/v1/account/credits \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY"

TypeScript (fetch)

const response = await fetch(
  "https://api.reelsbuilder.ai/api/v1/account/credits",
  {
    headers: {
      Authorization: `Bearer ${process.env.REELSBUILDER_API_KEY}`,
    },
  },
);
const data = await response.json();

Python (requests)

import os, requests

response = requests.get(
    "https://api.reelsbuilder.ai/api/v1/account/credits",
    headers={"Authorization": f"Bearer {os.environ['REELSBUILDER_API_KEY']}"},
)
data = response.json()

Rotation

Rotate a compromised key from /api-access → Regenerate. The old key is invalidated immediately. There is no overlap window in Phase 1 — automate a tight cutover. Phase 2 will add second-key issuance for zero-downtime rotation.

Legacy key migration

Accounts created before 2026-05-15 may have plaintext keys stored in the database under the legacy schema. The API auto-migrates these on first use: a valid plaintext key is accepted once, then transparently rotated to the hashed shape (the raw key still works after migration — no client change required).

Track migration progress with web/scripts/audit-api-key-migration.ts (read-only).

Security checklist

• Store keys in environment variables, never in source control.
• Use a server-side proxy for browser clients; never call the API directly from frontend JavaScript with a live key.
• Treat the key like a password. Anyone with it can spend your credits and access your account's generated content.
• Set up webhook signature verification to confirm callbacks really came from ReelsBuilder.
• Rotate immediately if a key is leaked in logs, screenshots, or shared terminals.

Common authentication errors

See the full errors reference.

• 401 AUTH_INVALID_KEY — Key missing, malformed, expired, or revoked.
• 403 AUTH_FORBIDDEN — Key is valid but lacks permission for the requested resource (e.g., admin-only endpoint).
• 402 CREDIT_INSUFFICIENT — Key is valid but the account has no credits remaining.

Next

Set up idempotency keys so retries don't double-charge credits, then wire webhook verification for async jobs.