Authentication

API requests that modify or render resources require a valid API token (API key). Tokens are scoped to a space and used via the Authorization header.

API keys

1. Go to Settings → Space → Developers.
2. Click Create API key, give it a name and optional expiry.
3. Copy the token whenever you need it; you can also use Copy next to the masked value in the list. Store it securely and avoid sharing it publicly.

Tokens can be revoked from the same Developers page.

Demo tokens (no account)

For quick demos — and so AI agents can try Bannx without signing up — you can mint a short-lived demo token. Demo tokens are stored only in Redis (never in the database), expire after ~1 hour, and can render public templates only. They never consume any space's credits.

To prevent abuse, each client IP can mint at most 5 demo tokens per rolling hour; after that, POST /api/demo-token returns 429 Too Many Requests until the window resets.

# Mint a demo token (no auth required)
curl -s -X POST https://your-app.bannx.app/api/demo-token

{
  "token": "demo_xxxxxxxxxxxxxxxxxxxxxxxx",
  "tokenType": "demo",
  "expiresAt": 1750000000000,
  "ttlSeconds": 3600,
  "quota": { "limit": 5, "used": 1, "remaining": 4 }
}

Use the token against GET /api/render/:pageId for a public template, either as a Bearer header or the demo query parameter:

# Header
curl -L -H "Authorization: Bearer demo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://your-app.bannx.app/api/render/PAGE_ID?format=png&output=binary" \
  --output demo.png

# Query param (handy for <img> src)
curl -L \
  "https://your-app.bannx.app/api/render/PAGE_ID?format=png&output=binary&demo=demo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --output demo.png

Demo tokens are intended for evaluation only. For private templates, higher limits, and credit-backed usage, create an API key as described above.

GET render URL secret (gt)

For GET /api/render/:pageId, when the template requires a GET token (default), you can either use a normal API key in the header or a shorter GET render URL secret in the query string as gt. Create, rotate, or clear it under Settings → Space → Developers (same page as API keys). The secret is scoped to the space; use it only in URLs you control, since query strings can appear in logs and referrers.

Sending the token

Send the token in the Authorization header as a Bearer token:

Authorization: Bearer your_api_token_here

Example with cURL

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-app.bannx.app/api/render/PAGE_ID?format=png"

Example with fetch

const response = await fetch(
  `https://your-app.bannx.app/api/render/${pageId}?format=png`,
  {
    headers: {
      'Authorization': `Bearer ${apiToken}`,
    },
  }
);
const imageBlob = await response.blob();

token query parameter (not allowed)

Passing an API key as ?token=... is not allowed and returns 400 Bad Request. Use the Authorization header for API keys, or the gt parameter for the dedicated GET render secret.

Errors

Token scope

• Each token is tied to one space. Rendering and other operations use that space's templates, pages, and credits.
• Expired tokens (if you set an expiry) are rejected with 401.
• Revoked keys no longer work; create a new key if needed.