Per-user billing

This guide walks through the headline qlaud workflow — minting a qlk_live_… key per end-user of your app, enforcing a per-user spending cap, and generating invoices from per-key usage.

Mental model

Stripe pattern	qlaud equivalent
`Customer`	A `qlk_live_…` key with `name: "user_<id>"`
Subscription / metered usage	Per-key `usage_events` we record on every API call
Spending limit	`max_spend_usd` enforced on the key
Webhook on overage	(coming soon) `cap_exceeded` webhook
Invoice	`GET /v1/usage` → fold into Stripe `InvoiceItem.create()`

You hold one master key (scope: 'admin') that lets you mint and revoke per-user keys. Every other key is scope: 'standard' and can only be used for inference.

Architecture

                                                   ┌── /v1/messages ─→ Claude
your user ──HTTP──→ your backend ──qlk_live_user_42──→ qlaud ──┼── /v1/audio/* ─→ OpenAI
                                                   └── /v1/videos ──→ Sora 2

           Master key holder (you)
              ↓
        POST /v1/keys ──── mint per-user keys
        GET  /v1/usage ─── pull per-user spend
        DEL  /v1/keys/:id  revoke when user churns

Step 1 — Mint your master key

In the dashboard, create a key with scope Master (admin). Store it as QLAUD_MASTER_KEY in your backend’s secret manager. Never expose this key to clients — it can mint other keys. When a user signs up to your app, mint a qlaud key for them with their monthly cap.

// pages/api/signup.ts (or wherever you handle signup)
async function onUserSignup(user: { id: string; email: string }) {
  const r = await fetch('https://api.qlaud.ai/v1/keys', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QLAUD_MASTER_KEY!,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      name: `user_${user.id}`,        // we surface this in /v1/usage
      max_spend_usd: 5,                // hard cap; gateway-enforced
    }),
  });
  const { id, secret } = await r.json();

  // Store with the user — `secret` is shown ONCE; we only keep a hash.
  await db.users.update(user.id, {
    qlaud_key_id: id,
    qlaud_key_secret: secret,
  });
}

# users/views.py (or wherever you handle signup)
import os, requests

def on_user_signup(user):
    r = requests.post(
        "https://api.qlaud.ai/v1/keys",
        headers={"x-api-key": os.environ["QLAUD_MASTER_KEY"]},
        json={
            "name": f"user_{user.id}",
            "max_spend_usd": 5,
        },
    )
    body = r.json()
    user.qlaud_key_id = body["id"]
    user.qlaud_key_secret = body["secret"]   # shown ONCE
    user.save()

curl https://api.qlaud.ai/v1/keys \
  -H "x-api-key: $QLAUD_MASTER_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"user_42","max_spend_usd":5}'

# {
#   "id": "0e2c3a91-...",
#   "name": "user_42",
#   "secret": "qlk_live_abc...wxyz",
#   "prefix": "qlk_live_abcd…wxyz",
#   "scope": "standard",
#   "max_spend_usd": 5
# }

The secret is returned once at creation time. Save it immediately — we only store its SHA-256 hash. If you lose it, you must revoke the key and mint a new one.

Step 3 — Use the per-user key for inference

In your app’s request flow, swap the master key for the user’s key when calling qlaud. The cap is enforced gateway-side — you don’t need any extra logic.

// When user_42 calls your /chat endpoint:
const userKey = await db.users.findById(user.id).qlaud_key_secret;

const r = await fetch('https://api.qlaud.ai/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': userKey,
    'anthropic-version': '2023-06-01',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-6',
    max_tokens: 1000,
    messages,
  }),
});

// If user_42 has hit their $5 cap, qlaud returns 402 with:
// {"error":{"type":"authentication_error",
//           "message":"this API key has reached its spending cap..."}}

Step 4 — Bill at month-end

Pull per-user spend from qlaud and create Stripe invoice items.

import os, requests, stripe
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

usage = requests.get(
    "https://api.qlaud.ai/v1/usage",
    headers={"x-api-key": os.environ["QLAUD_MASTER_KEY"]},
).json()

for k in usage["by_key"]:
    user = db.users.find_by_qlaud_key_id(k["key_id"])
    if k["cost_micros"] == 0 or not user.stripe_customer_id:
        continue

    stripe.InvoiceItem.create(
        customer=user.stripe_customer_id,
        amount=int(k["cost_micros"] / 100),    # micro-dollars → cents
        currency="usd",
        description=f"AI usage — {k['request_count']} requests",
    )

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const usage = await fetch('https://api.qlaud.ai/v1/usage', {
  headers: { 'x-api-key': process.env.QLAUD_MASTER_KEY! },
}).then((r) => r.json());

for (const k of usage.by_key) {
  const user = await db.users.findByQlaudKeyId(k.key_id);
  if (k.cost_micros === 0 || !user?.stripeCustomerId) continue;

  await stripe.invoiceItems.create({
    customer: user.stripeCustomerId,
    amount: Math.floor(k.cost_micros / 100),    // micro-dollars → cents
    currency: 'usd',
    description: `AI usage — ${k.request_count} requests`,
  });
}

Optional — date-range billing

/v1/usage defaults to month-to-date. Pass from_ms and to_ms (UTC milliseconds) to scope to any window:

# Last 30 days
NOW=$(date +%s)000
THEN=$(( NOW - 30 * 86400 * 1000 ))
curl "https://api.qlaud.ai/v1/usage?from_ms=$THEN&to_ms=$NOW" \
  -H "x-api-key: $QLAUD_MASTER_KEY"

Optional — drill down to one user

curl "https://api.qlaud.ai/v1/keys/<key_id>/usage" \
  -H "x-api-key: $QLAUD_MASTER_KEY"

# Returns: { total_cost_micros, max_spend_micros, events: [...] }
# events = last 100 requests with model, status, latency_ms, cost

Revoking a key

When a user churns or you need to roll a key:

curl -X DELETE https://api.qlaud.ai/v1/keys/<key_id> \
  -H "x-api-key: $QLAUD_MASTER_KEY"

Revocation propagates to our cache immediately — the key stops working on the next request, no waiting for TTL.

What you didn’t have to build

Per-user usage tracking → usage_events table on our side
Per-user spending caps → max_spend_micros column, KV-cached check
Failed-payment handling for AI usage → 402 from qlaud, propagate to user
Per-provider billing reconciliation → one wallet, one invoice from us
Storing customer-facing AI prices → catalog already includes our 7% markup

Coming soon

Webhooks — cap_exceeded, low_balance, key_revoked. POST to your URL on event.
Per-key recharge — POST /v1/keys/:id/credit to add credit on a single user-key without touching your master wallet (for “user paid you, push credit to their key” flows).
@qlaud/sdk — Stripe-SDK-shaped Node + Python clients with qlaud.keys.create(), qlaud.usage.list(), etc.

Get started

Tutorials

Concepts

Integrations

Per-user billing

Mental model

Architecture

Step 1 — Mint your master key

Step 3 — Use the per-user key for inference

Step 4 — Bill at month-end

Optional — date-range billing

Optional — drill down to one user

Revoking a key

What you didn’t have to build

Coming soon

​Mental model

​Architecture

​Step 1 — Mint your master key

​Step 2 — Mint a per-user key on signup

​Step 3 — Use the per-user key for inference

​Step 4 — Bill at month-end

​Optional — date-range billing

​Optional — drill down to one user

​Revoking a key

​What you didn’t have to build

​Coming soon

Mental model

Architecture

Step 1 — Mint your master key

Step 2 — Mint a per-user key on signup

Step 3 — Use the per-user key for inference

Step 4 — Bill at month-end

Optional — date-range billing

Optional — drill down to one user

Revoking a key

What you didn’t have to build

Coming soon