Skip to content

Use cases

Meter usage & sell credits

Sell consumption on top of licensing — renders, API calls, AI generations, exports — with Keyright credit pools bound to a license: price each action, fund a pool, then check balances and spend credits from your app with dry-run pricing and idempotent retries, online or from a signed offline block.

Goal

Charge for usage, not just for the seat. Licensing answers “is this customer allowed to run the software?”; credits answer “how much have they used?” — so you can sell renders, API calls, AI generations, exports or any metered action on top of a license, with quotas and overage. Your app prices an action, spends credits against a pool bound to the customer’s license key, and Keyright deducts atomically and records the usage.

Throughout, $BASE is your issuing service URL and $TOKEN is a product admin token — see Getting started.

When to use it

  • Use this if your product sells consumption (per render, per export, per generation) alongside — or instead of — a flat seat license, with quotas, top-ups and overage.
  • Use this if you need to show a cost before the user commits (dry-run pricing) or to meter on air-gapped machines (signed credit blocks).
  • Don’t use this if you only sell seats and perpetual/term licenses — credits are purely additive and a product that never configures a pool never touches them.

The model

  • Credit pool — a balance of credits bound to a license key. A license can have one or more pools (e.g. a monthly “renders” pool and a top-up “overage” pool), each with a unit name you choose.
  • Action cost — what one unit of a metered action costs, in credits. You define costs per product (e.g. render = 1, hd-export = 5).
  • Consume — your app spends credits for an action; Keyright checks the balance, deducts atomically, and records the usage. Balance reads what’s left.

Consumption uses license-key auth — the same key your app already holds, no admin token. The two calls are online only (there’s no offline fallback); for disconnected machines, see air-gapped credit blocks.

Your appholds the license keybalance() · consume()key authKeyrightprice = action cost × qtychecks + deducts atomicallydeductCredit poolbound to the license keyunit · remaining balancedryRunprice an action without chargingidempotencyKeya retry replays — never double-chargesAir-gappedsigned credit block spent offline, reconciled on reconnect
A credit pool is bound to a license key; your app prices and spends against it with the key it already holds — safely retried, online or from a signed offline block.

What you do (vendor side)

One-time setup: price each action, create a pool bound to a license, and fund it. Do it from the dashboard (the credits section of the product) or the admin API with your product admin token.

SVC=https://keyright.delta1labs.com
# 1. what an action costs
curl -X POST "$SVC/admin/products/<your-product>/action-costs" \
     -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"action":"render","credits":1}'
# 2. a pool bound to a license key  (-> returns {"id":"pool_..."})
curl -X POST "$SVC/admin/credit-pools" \
     -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"licenseId":"<LICENSE_KEY>","product":"<your-product>","name":"Render credits","unit":"renders"}'
# 3. fund it
curl -X POST "$SVC/admin/credit-pools/<POOL_ID>/grant" \
     -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"amount":1000}'

Pools also support top-up, transfer, scheduled resets and low-balance thresholds; usage is queryable per pool and across products for reporting (GET /admin/usage). See the HTTP API reference for the full admin surface.

The Usage & credits overview in Keyright with four stat tiles — Entitled 5,000 renders, Consumed 70 (1% of everything entitled), Available 4,930 renders, and Pools 1 (none exhausted) — above a 'By pool' table listing an 'AI renders' pool (acme-app · renders) bound to license LIC-4AF59FF333A887E931AF with 5,000 entitled, 70 consumed and 4,930 available.
The Usage & credits dashboard: an "AI renders" pool bound to a license key, funded with 5,000 renders, 70 consumed and 4,930 left — the same balance your app reads with balance().

In your code

Every SDK exposes the same two calls; over raw HTTP they’re POST /v1/balance and POST /v1/consume. Two features make them safe in production:

  • dryRun — price an action without charging, e.g. to show a cost before the user commits.
  • idempotencyKey — a key you supply so a retried call replays the first result instead of charging twice. Always pass one for a real charge, so a network retry never double-bills.

consume returns a status of ok, insufficient (not enough credits), unknown_action (no cost configured), no_pool / ambiguous_pool (no single pool to draw from), or not_found.

// .NET
var pools = await client.BalanceAsync(licenseKey);          // remaining balance per pool
var quote = await client.ConsumeAsync(licenseKey, "render", dryRun: true);   // price only
var res   = await client.ConsumeAsync(licenseKey, "render", quantity: 1, idempotencyKey: txnId);
if (res.Status == "ok") Console.WriteLine($"charged {res.TotalCost} {res.Unit}, {res.Balance} left");
// Node.js
const { pools } = await client.balance(licenseKey);
const quote = await client.consume(licenseKey, 'render', { dryRun: true });
const res   = await client.consume(licenseKey, 'render', { quantity: 1, idempotencyKey: txnId });
# Python
pools = client.balance(license_key)
quote = client.consume(license_key, "render", dry_run=True)
res   = client.consume(license_key, "render", quantity=1, idempotency_key=txn_id)
// Java
List<PoolBalance> pools = client.balance(licenseKey);
ConsumeResult quote = client.consume(licenseKey, "render", 1, null, true);        // dry run
ConsumeResult res   = client.consume(licenseKey, "render", 1, txnId, false);      // real charge
# Any language (raw HTTP) — the same two calls, authenticated with the license key, no admin token
curl -s -X POST "$BASE/v1/balance" -H "content-type: application/json" \
     -d '{"key":"<LICENSE_KEY>","product":"<your-product>"}'                 # remaining balance per pool

curl -s -X POST "$BASE/v1/consume" -H "content-type: application/json" \
     -d '{"key":"<LICENSE_KEY>","product":"<your-product>","action":"render","dryRun":true}'   # price only

curl -s -X POST "$BASE/v1/consume" -H "content-type: application/json" \
     -d '{"key":"<LICENSE_KEY>","product":"<your-product>","action":"render","quantity":1,"idempotencyKey":"<txn-id>"}'
# -> { "status":"ok", "totalCost":1, "unit":"renders", "balance":4929 }   (fail closed on any non-ok status)

Any language without an SDK uses these HTTP endpoints directly — see Use the HTTP API directly. Runnable walkthroughs for all of the above (operation 6) are in the SDK samples on GitHub.

When a pool runs out consume returns insufficient and does not deduct. Your app decides whether to block the action, queue it, or prompt the customer to top up — configure an overage pool to allow controlled overage.

Air-gapped credit blocks

Disconnected machines can still meter: the vendor issues a signed credit block (a fixed allotment the client spends offline), and reconciles the spent amount when the machine next reconnects. This keeps usage-based products working on fully air-gapped deployments. Air-gapped blocks are an entitlement of the higher self-hosted tiers. See Run offline / air-gapped for the broader offline story.

Cloud vs Self-hosted

The credit model, the two runtime calls and the admin setup are identical in both modes. The differences:

  • Base URL / token. $BASE/SVC is https://keyright.delta1labs.com on Keyright Cloud or your own issuing-service URL when self-hosted; the runtime balance/consume calls authenticate with the customer’s license key either way.
  • Air-gapped credit blocks are a feature of the higher self-hosted tiers (an air-gapped machine can’t reach Keyright Cloud at all), whereas online metering works on both.

Verify

  1. Price an action, create a pool on a test license, and grant it credits — confirm the pool shows the funded balance (BalanceAsync / POST /v1/balance).
  2. consume the action with dryRun: true and confirm it returns the price with the balance unchanged.
  3. consume for real with an idempotencyKey — confirm status: ok, the balance drops by the action cost, and the usage is recorded.
  4. Call consume again with the same idempotencyKey — confirm it replays the first result and does not charge again.
  5. Drain the pool and confirm consume returns insufficient without deducting.

See also