Per-customer usage dashboards with Client Tokens

25 min

Your API key is the key to the building. You would never post it through a customer's letterbox, but that is what putting it in browser code does. A Client Token is a day pass instead: it opens one door, for one person, and it is void by lunchtime. By the end, every signed-in user can talk to a model straight from the browser on a day pass, and see a chart of their own spend that your server fetched with the real key.

Prerequisites

• A Ringside API key (completed the quickstart)
• A Next.js app with working server-side auth (any provider)
• A chart library (recharts works, or plain CSS bars)
• Users already making Ringside calls tagged with FC-Customer
• 25 minutes

Step 1

Lazy-create an FC-Customer per user

// idempotent on external_id

Every signed-in user needs a 1:1 Ringside Customer so their spend is bucketed. Use the user's own id as external_id and look it up via ext:<id>.

On first login the lookup 404s, then you POST to create with display_name and any metadata you want back later. On every subsequent login the GET returns the existing row: no dupes, no race. Run this in your auth callback or on any server-side page load.

What just happened

ext: lookups are Ringside's idempotency primitive. You never need to store the cus_... id in your own database - your user id is already the key. A customer belonging to another developer account reads as a 404, not a 403, so ids can't be probed.

lib/fc.ts

// in your auth handler (server component / route):

async function ensureFcCustomer(user) {

const r = await fetch(`https://api.fightclub.pro/v1/customers/ext:${user.id}`, {

headers: { Authorization: `Bearer ${process.env.FC_API_KEY}` }});

if (r.ok) return (await r.json()).id;

const created = await fetch("https://api.fightclub.pro/v1/customers", {

method:"POST", headers:{/*...*/},

body: JSON.stringify({ external_id: user.id, display_name: user.email,

metadata:{ plan: user.plan }})});

return (await created.json()).id;

}

✓cus_a1b2c3 (lazily created on first login)

█

Step 2

Mint a Client Token

// short-lived, scoped, origin-locked

A Client Token is a signed token scoped to one customer and a fixed set of capabilities. TTL runs from 60 seconds to 1 hour and it cannot be refreshed. Mint a new one on page load, or shortly before the old one expires.

The mint body takes scope, origin_allowlist, ttl_seconds, rpm_limit and bind_ip. origin_allowlist binds the token to your domain; scope decides what it may call.

Valid scopes today are chat, conversations, embeddings, moderations and assistants_threads. Inference only. There is no browser-readable scope for customer or usage records, which is what Step 4 works around.

~/dashboard

$ curl -X POST https://api.fightclub.pro/v1/customers/cus_a1b2c3/client_tokens -H "Authorization: Bearer $FC_API_KEY" -d @token.json

# token.json:

# {"scope":["chat"],

# "origin_allowlist":["https://app.example.com"],

# "ttl_seconds":300,

# "rpm_limit":20,

# "bind_ip":true}

✓201 {"token":"eyJhbGci...","jti":"ct_9f2","expires_at":"2026-04-21T12:05:00Z",

"scope":["chat"],"rpm_limit":20,"customer_id":"cus_a1b2c3"}

█

Step 3

Expose /api/mint-client-token

// server-side gatekeeper

Browser code can't mint its own token; that would require exposing your Bearer key. Proxy through a Next.js route handler that first checks your own session, then calls Ringside with the server-side key.

Return the Ringside response straight through. Your server stays small; your Bearer key stays in your env vars. The browser gets token, expires_at and customer_id, and uses the token as Authorization: Client <token> on its chat calls.

What just happened

Treat this route like a mint for physical day passes: if your own auth is compromised an attacker gets a 5-minute, origin-locked, rate-limited chat token for one customer. No broader blast radius. If a token expires mid-session the next call fails auth - re-call /api/mint-client-token, or rotate preemptively at expires_at minus 30s.

app/api/mint-client-token/route.ts

$ cat > app/api/mint-client-token/route.ts

import { getSession } from "@/lib/auth";

import { ensureFcCustomer } from "@/lib/fc";

export async function POST() {

const user = await getSession();

if (!user) return new Response("Unauthorized", { status: 401 });

const customerId = await ensureFcCustomer(user);

const r = await fetch(`https://api.fightclub.pro/v1/customers/${customerId}/client_tokens`, {

method:"POST", headers:{Authorization:`Bearer ${process.env.FC_API_KEY}`},

body: JSON.stringify({scope:["chat"],ttl_seconds:300,

origin_allowlist:["https://app.example.com"]})});

return new Response(await r.text(), {headers:{"content-type":"application/json"}});

}

✓Secure mint endpoint ready

█

Step 4

Read the spend on the server

// Bearer stays home

Spend is a billing record, not inference, so it is deliberately out of reach of a Client Token. Fetch it where the real key already lives: a server component or route handler calling GET /v1/customers/:id/usage?group_by=day with your Bearer key, then hand the numbers down as props.

The report returns a total object (llm_cost_usd, input_tokens, output_tokens, request_count) plus one buckets entry per day. Other group_by values: model, tag, property, conversation.

For lifetime figures and the budget you set, hit GET /v1/customers/:id instead: it returns lifetime_spend_usd, monthly_budget_usd and wallet_balance_usd.

What just happened

This is the split that makes the whole design safe: the browser holds a capability that can only spend, never read the books, and the reading happens on a machine that already holds the key. Want the number to move live? Re-fetch it from your own route on an interval, or revalidate the server component. The Bearer key still never leaves your infra.

app/usage/page.tsx

$ cat > app/usage/page.tsx

// server component - the Bearer key is read here and never shipped

import { getSession } from "@/lib/auth";

import { ensureFcCustomer } from "@/lib/fc";

import { UsageChart } from "./UsageChart";

export default async function UsagePage() {

const user = await getSession();

const cid = await ensureFcCustomer(user);

const r = await fetch(

`https://api.fightclub.pro/v1/customers/${cid}/usage?group_by=day`,

{ headers:{ Authorization: `Bearer ${process.env.FC_API_KEY}` },

cache:"no-store" });

const report = await r.json();

return <UsageChart total={report.total} buckets={report.buckets} />;

}

✓{"total":{"llm_cost_usd":1.4832,"request_count":318,...},

"buckets":[{"key":"2026-04-18","llm_cost_usd":0.2140,"request_count":47},...],

"from":"...","to":"...","group_by":"day"}

█

Step 5

Chart the numbers

// recharts or CSS bars

The daily buckets are already chart-shaped. Feed buckets straight into a Recharts <LineChart> with dataKey="llm_cost_usd" against key on the X axis.

If you'd rather not add a chart lib, a grid of CSS flex bars with height: {spend / max * 100}% works fine and ships zero JS.

UsageChart.tsx

$ pnpm add recharts

✓added recharts 2.13.0

// UsageChart.tsx - pure client component, no token, no key

"use client";

import { LineChart, Line, XAxis, YAxis } from "recharts";

type Bucket = { key: string; llm_cost_usd: number };

export function UsageChart({ buckets }: { buckets: Bucket[] }) {

return <LineChart width={500} height={200} data={buckets}>

</LineChart>;

}

✓Per-customer daily spend chart rendering

█

You built it.

Every signed-in user talks to a model from the browser on a token that expires in minutes, and sees a chart of their own spend that your server fetched with the real key. The Bearer key never left your infra, and the thing the browser holds cannot read anyone's books, including its own owner's.

Example: per-customer budgets →Endpoint reference: /v1/customers/:id/client_tokens →