Per-customer usage dashboards with Client Tokens

25 min

By the end every signed-in user will have a live chart of their own AI spend, fetched safely from the browser with a short-lived, scoped Client Token so no Bearer key ever touches the client.

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 you 404, then POST to create. On every subsequent login the GET returns the existing row with 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.

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, metadata:{ email: user.email }})});

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 JWT scoped to one customer and one endpoint whitelist. It expires in 60-3600 seconds and can't be refreshed. Mint a new one on every page load (or every 4 minutes, whichever is sooner).

origin binds the token to your domain; allowed_endpoints keeps it from reading anything other than this one customer's row.

~/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,

# "bind_ip":true}

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

█

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.

What just happened

Treat this route like a mint for physical tokens: if your own auth is compromised an attacker only gets a 5-minute window to read one customer's spend. No broader blast radius.

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

Poll /v1/customers/:id from the browser

// Authorization: Client <jwt>

Fetch the token once on mount, then poll /v1/customers/:id every 5 seconds with Authorization: Client <jwt>.

The response has spend_usd_mtd, request_count_mtd, and any budgets you've set. Wire it straight to state.

What just happened

If the token expires mid-poll you'll get 401 invalid_client_token. Re-call /api/mint-client-token on that failure - or preemptively rotate at token.expires_at minus 30s.

app/usage/UsagePoll.tsx

$ cat > app/usage/UsagePoll.tsx

"use client";

import { useEffect, useState } from "react";

export function UsagePoll() {

const [spend, setSpend] = useState(0);

useEffect(() => {

let tok: string, cid: string;

(async () => {

const r = await fetch("/api/mint-client-token", {method:"POST"});

const j = await r.json(); tok = j.token; cid = j.customer_id;

const tick = async () => {

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

headers:{ Authorization: `Client ${tok}` }});

const d = await r.json(); setSpend(d.spend_usd_mtd);

};

tick(); const id = setInterval(tick, 5000);

return () => clearInterval(id);

})();

}, []);

return <div>MTD: ${spend.toFixed(4)}</div>;

}

█

Step 5

Chart the numbers

// recharts or CSS bars

Widen the allowed_endpoints to include /v1/usage with group_by=day and feed the resulting array straight into a Recharts <LineChart>.

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 - poll /v1/usage?group_by=day on the client token

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

export function UsageChart({ data }: { data: {day:string,spend:number}[] }) {

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

</LineChart>;

}

✓Live per-customer usage chart rendering

█

You built it.

Every signed-in user sees their own live AI spend. Your Bearer key never left the server. Tokens expire in minutes. Budgets, alerts, and rate limits are a header away.

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