Embed a browser chatbot

The problem with a key in the browser

A Ringside developer key is ko_ followed by 64 hex characters, sent as Authorization: Bearer ko_<key>. It carries your whole account: every customer, every wallet, every scope the key was granted. Put that string in a script tag or a fetch call and anyone with devtools open has it. There is no test-vs-live split to soften the blow, so a leaked key is a leaked account.

A client token is the answer. It is a signed JWT your server mints on demand, pinned to one customer, scoped to a tiny allowlist of browser-safe endpoints, time-boxed to minutes and rate-limited per token. The browser holds it; the browser never holds the ko_ key. When the user logs out you revoke the token and any copy that leaked dies on the next request.

The mental model

  your server (holds ko_ key)                browser (holds JWT)
  ---------------------------                --------------------
  POST /v1/customers/cus_42/client_tokens
    Authorization: Bearer ko_...      --->   201 { token, jti, expires_at }
                                                   |
                                      hand JWT to the page (memory)
                                                   |
                                                   v
                                   POST /v1/chat/completions
                                     Authorization: Client <jwt>
                                     Origin: https://app.example.com
                                                   |
                                          stream tokens via SSE
                                                   |
  on logout:                                       v
  DELETE .../client_tokens/ctok_...  <---   (JWT now dead next request)

• ·The JWT is never stored server-side. Ringside keeps only a revocation registry row keyed by the token jti (prefix ctok_), holding its expiry, scopes, rpm limit, origin allowlist and optional IP-binding hash.
• ·Verification is stateless crypto (EdDSA / Ed25519 signature, plus exp, nbf, iss, aud checks) followed by one registry lookup that collapses unknown, revoked and expired into the same answer.
• ·Client tokens are un-refreshable by design. You mint a new one per session rather than renewing an old one.

Step 1: mint a client token on your server

Call POST /v1/customers/{id}/client_tokens with your developer key. The key must hold the api:client_tokens scope; without it you get 403 insufficient_scope. The {id} is a customer id (cus_...), or you can address the customer by external id with ext:<external_id>. The customer must exist and be active, or the mint returns 404 (cross-tenant and unknown ids both 404 so they are not enumerable).

A successful mint is 201 with the JWT and its metadata. The token string is the only place you ever see the JWT; persist nothing but the jti if you want to revoke it later, and you can also list active tokens with a GET to the same path.

curl -sS -X POST https://api.fightclub.pro/v1/customers/cus_42/client_tokens \
  -H 'Authorization: Bearer ko_7f3c...<64 hex>' \
  -H 'Content-Type: application/json' \
  -d '{
    "scope": ["chat"],
    "ttl_seconds": 600,
    "rpm_limit": 30,
    "origin_allowlist": ["https://app.example.com"]
  }'

Doing it from your backend

In practice this lives behind your own session check: when a logged-in user opens the chat widget, your endpoint authenticates the user, maps them to a Ringside customer and mints a token scoped to that customer alone. The browser gets a JWT that can only ever spend against cus_42, never the rest of your account.

import express from 'express';

const app = express();
const RINGSIDE = 'https://api.fightclub.pro/v1';

app.post('/chat-token', requireLogin, async (req, res) => {
  // map your user -> a Ringside customer id you created earlier
  const customerId = req.user.ringsideCustomerId; // e.g. "cus_42"

  const r = await fetch(`${RINGSIDE}/customers/${customerId}/client_tokens`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.RINGSIDE_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      scope: ['chat'],
      ttl_seconds: 600,
      rpm_limit: 30,
      origin_allowlist: ['https://app.example.com'],
    }),
  });

  if (!r.ok) {
    const body = await r.json();
    // branch on body.error.code, never the human message
    return res.status(502).json({ error: body.error?.code ?? 'mint_failed' });
  }

  const { token, jti, expires_at } = await r.json();
  // store jti against the session so logout can revoke it
  req.session.chatTokenJti = jti;
  res.json({ token, expires_at });
});

Step 2: call chat completions from the browser

Hand the JWT to the page (keep it in memory, not localStorage) and call POST /v1/chat/completions with Authorization: Client <jwt>. Set stream: true to read the response as Server-Sent Events. The model reference still needs a Ringside prefix; a bare name like gpt-4o returns 400 invalid_model_ref. Use fc:openai/gpt-4o-mini to pin, or match:anthropic/sonnet>=4 to resolve.

// token came from POST /chat-token above; never the ko_ key
async function streamReply(token, userText, onDelta) {
  const res = await fetch('https://api.fightclub.pro/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: `Client ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'fc:openai/gpt-4o-mini',
      stream: true,
      messages: [{ role: 'user', content: userText }],
    }),
  });

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(error.code); // e.g. client_token_rate_limit_exceeded
  }

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buf = '';
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buf += decoder.decode(value, { stream: true });
    const lines = buf.split('\n');
    buf = lines.pop() ?? '';
    for (const line of lines) {
      if (!line.startsWith('data: ')) continue;
      const data = line.slice(6);
      if (data === '[DONE]') return;
      const chunk = JSON.parse(data);
      const delta = chunk.choices?.[0]?.delta?.content;
      if (delta) onDelta(delta);
    }
  }
}

The browser sends the Origin header automatically on a cross-origin fetch, which is what the origin allowlist checks against. You do not set Origin yourself; the browser does, and the user agent will not let a page forge it.

What a client token can and cannot reach

Client tokens fail closed. They reach only a small allowlist of browser-safe endpoints, gated by the scope you minted. Every other /v1/* route returns 403 endpoint_not_allowed_for_client_token when called with a Client header, including the token-management routes themselves, so a leaked browser token can never mint or revoke tokens.

Origin enforcement

When a token pins an origin_allowlist, the incoming Origin header must exactly match one entry on every call. This is CORS-lite enforcement at the credential layer: the comparison is a literal string match against the allowlist, so https://app.example.com and https://app.example.com/ (trailing slash) and http://app.example.com (wrong scheme) are three different values.

• ·No Origin header at all is rejected when an allowlist is set. That is deliberate: a curl call with no origin is not trusted to spend a browser token, so the token is only useful from a real browser on an allowlisted page.
• ·Match the value your browser actually sends. It is scheme + host + port with no path and no trailing slash, e.g. https://app.example.com or https://app.example.com:8443.
• ·Leave origin_allowlist unset only if the token is otherwise constrained (short TTL, low rpm, IP-bound). An unpinned token works from any origin that holds it.

{
  "error": {
    "type": "permission_error",
    "code": "origin_not_allowed",
    "message": "Origin 'https://evil.example' is not in the token's allowlist"
  }
}

TTL strategy

TTL is your blast-radius dial. The default is 900 seconds (15 minutes), the floor is 60 and the ceiling is 3600 (1 hour). A leaked token is only dangerous until it expires, so shorter is safer, but too short and a long chat session dies mid-conversation and the page has to re-mint. Pick a TTL that covers a realistic session, not a realistic day.

Expiry is enforced twice: the JWT exp claim fails the signature-time check (verification returns expired), and the registry row's expires_at is re-checked on lookup. Either way an expired token returns 401 invalid_client_token with WWW-Authenticate: Client realm="ringside". The browser should treat that as "fetch a new token and retry once".

Step 3: revoke on logout

Expiry handles the slow case; revocation handles "right now". When the user logs out, or you detect abuse, revoke the token server-side. Revocation flips the registry row, and because every chat call does a registry lookup, the next request with that JWT returns 401 even though the signature is still cryptographically valid.

curl -sS -X DELETE \
  https://api.fightclub.pro/v1/customers/cus_42/client_tokens/ctok_9a1b2c3d4e5f60718293a4b5 \
  -H 'Authorization: Bearer ko_7f3c...<64 hex>'
# -> 204 No Content

Rate limits on a client token

Each token carries its own per-minute ceiling (rpm_limit, default 60, max 600, never above the customer's own rpm_limit). It sits inside the wider four-layer rate-limit stack and the lowest applicable limit wins. So a token with rpm_limit: 30 is capped at 30/min even if the customer allows 600.

• ·Edge per-IP (outermost)
• ·Per-client-token (this rpm_limit)
• ·Per-developer
• ·Per-customer (innermost)

On a normal response, read X-RateLimit-Remaining for the count left in the current window. On a 429 you get Retry-After (integer seconds) and, for a token-rpm breach, code: "client_token_rate_limit_exceeded" with a retry_after_seconds field in the body. There is no X-RateLimit-Limit or X-RateLimit-Reset header.

{
  "error": {
    "type": "rate_limit_error",
    "code": "client_token_rate_limit_exceeded",
    "message": "Client token RPM limit exceeded (limit=30/min)",
    "retry_after_seconds": 42
  }
}

Failure modes and how to handle them

Every error body is { "error": { "type", "code", "message", ... } }. Branch on code, never the human message. The request id is the X-Request-Id response header, not a body field; log it when something goes wrong. The table below is the set you will actually see on the browser path.

Hard limits and defaults to remember

ttl_seconds

Default 900. Min 60, max 3600. Integer only.

rpm_limit

Default 60. Max 600, and clamped to the customer's rpm_limit if that is lower.

origin_allowlist entry

Up to 512 chars each, non-empty. Exact-match against the Origin header.

scope

Defaults to ["chat"]. Allowed: chat, conversations, embeddings, moderations, assistants_threads.

mint rate

100 mints per minute per customer, then 429 mint_rate_limit with Retry-After: 60.

chat messages size

Serialized messages cap at 100,000 bytes per chat request.

Related