Seller API

Authentication

Create a key in Settings › API keys. It is shown once; only an HMAC of it is stored. Send it in the header on every call, never in the URL (a key in the query string is refused with key_in_url).

curl https://<your API host>/seller/v1/apps \
  -H "Authorization: Bearer clv_live_…"

Keys can be limited to some apps, to a list of IPs or CIDR ranges, and given an expiry. Rotating a key creates a new one and keeps the old one working for 7 days; revoking is immediate.

Scopes

A key does only what its scopes allow; a key with no scope can do nothing. *:read scopes never change anything. Presets: read only, Discord bot (licenses, users, devices), store (licenses), full access.

Writes and idempotency

POST creates or acts, PATCH and PUT change, DELETE removes (licenses are soft-deleted). Send Idempotency-Key with any write: repeating it within 24 hours returns the first answer (marked Idempotent-Replayed: true) instead of acting twice. The same key with a different body is refused.

curl -X POST https://<host>/seller/v1/apps/app_…/licenses \
  -H "Authorization: Bearer clv_live_…" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{ "policyId": "pol_…", "count": 1, "email": "buyer@example.com" }'

Full license keys are returned once, in that answer. Store them or send them to the buyer right away.

Rate limits and pages

120 requests per minute per key, 600 on Premium. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Lists take ?limit=50&cursor=… and answer { data, nextCursor }. Every call is logged and visible in the dashboard.

Errors

{ "error": { "code": "forbidden_scope", "message": "…", "details": {}, "requestId": "…" } }

Endpoints

The machine-readable reference is GET /seller/v1/openapi.json (OpenAPI 3.1, generated from the same schemas that validate requests).

Webhooks

Each delivery is { id, type, createdAt, appId, data } with the header Clavis-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 of t.body with your signing secret. Check the time is within 5 minutes. Failed deliveries are retried about 15 times over 3 days and can be resent from the dashboard.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Resellers

A reseller key (created by the reseller in their desk) sees and acts only on the keys that reseller issued, and every key it creates is paid from their credit in the same transaction: an order larger than the balance is refused with insufficient_credit and nothing is charged.