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
actioncosts, 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.
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.
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/SVCishttps://keyright.delta1labs.comon Keyright Cloud or your own issuing-service URL when self-hosted; the runtimebalance/consumecalls 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
- 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). consumethe action withdryRun: trueand confirm it returns the price with the balance unchanged.consumefor real with anidempotencyKey— confirmstatus: ok, the balance drops by the action cost, and the usage is recorded.- Call
consumeagain with the sameidempotencyKey— confirm it replays the first result and does not charge again. - Drain the pool and confirm
consumereturnsinsufficientwithout deducting.
See also
- Getting started — issue and verify your first license.
- Sell upgrades & control versions — gate which builds a license can use.
- Run offline / air-gapped — signed offline leases, license files and credit blocks.
- HTTP API reference — the full admin + runtime endpoint map.