Selling with the Seller API

Before you start

• API keys live at Business › Seller API keys. Only the Owner and Admins of the workspace can create, rotate and revoke them.
• Every endpoint sits under /seller/v1 on your API address. Examples here use https://api.example.com; the dialog that shows a new key includes a sample curl command with the real address.
• Each key belongs to one workspace and can only reach that workspace's apps.
• The number of keys depends on your plan, by default 2 on Basic and 25 on Premium. The figure for your workspace is in the footnote of the keys page and at Account & organization › Plan & usage. The limit counts every key that is not revoked.

Creating an API key

1. Open Business › Seller API keys and click Create key.
2. In the New API key panel, fill in the fields in the table below.
3. Click Create key.
4. The Your new key dialog shows the full key. Copy it into your secrets manager and click Stored it.

Scopes

A key can only do what its scopes allow, and a :read scope never changes data. GET /seller/v1/me and GET /seller/v1/apps need no scope.

The presets: Read only (every :read scope), Discord bot (licenses, users, devices, read and write), Store (licenses:read and licenses:write, enough to sell and look up keys) and Full access (every scope).

The key is shown once

After that, each row in the list shows the name, the first 13 characters of the key, the scopes, the number of allowed IPs, the number of limited apps and Last used with the calling IP (updated at most once a minute). The clv_live_ prefix also helps secret scanners spot a key that was pushed to a repository by mistake.

Rotating and revoking

• Rotate (the circular arrow on the key row) creates a new key at once with the same name, scopes, apps, IPs and expiry date, shown once in the Your new key dialog. The old key keeps working for 7 more days so you can update your servers; its row says Grace ends with the time. After 7 days the old key is refused.
• Revoke asks for confirmation, then the key is refused from the next call on. This cannot be undone.
• Both buttons only appear on Active keys. Scopes, apps, IPs and expiry cannot be edited after creation; to change them, create a new key and revoke the old one.

Authentication

Send the key in the Authorization header on every call:

curl https://api.example.com/seller/v1/me \
  -H "Authorization: Bearer $CLAVIS_API_KEY"

/me returns the key's ID, name, prefix, scopes, allowed apps, key type (seller) and workspaceId. It is the quickest way to check a key is set up correctly. When a call is refused:

Every error has the same shape. Log the requestId so you can trace a call later:

{ "error": { "code": "forbidden_scope", "message": "This key needs the \"licenses:write\" scope", "requestId": "…" } }

Idempotent writes

The network can drop right after the server has created a key; calling again without protection creates a second key. The Idempotency-Key header solves this for every write (POST, PUT, DELETE):

• Use a value tied to the business event, for example the order number order-1042, up to 255 characters.
• For 24 hours, sending the same key with the same method, path and body returns the first response again, with the header Idempotent-Replayed: true, and nothing is done twice.
• Same key with a different body: 422 idempotency_mismatch. First call still running: 409 idempotency_in_progress; wait a moment and send it again.
• 5xx responses are not stored, so retrying with the same key runs the action again. Errors returned by the action itself, such as plan_limit or unknown_policy, are stored and replayed; once you fix the cause, use a new key.
• Idempotency records belong to each API key. A new key after a rotation does not see the old key's records.

Rate limits and pagination

• Each key gets 120 calls per minute, 600 if the workspace is on Premium. The counter resets at the start of each minute.
• Responses to calls that passed the key and IP checks carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the reset). Going over returns 429 rate_limited; wait for RateLimit-Reset and call again.
• Large lists (licenses, users, devices, sessions) accept limit from 1 to 100, default 50, plus cursor, and return { "data": [...], "nextCursor": "…" }. Pass nextCursor as cursor until it is null.

Example: selling licenses from a store backend

The scenario: a customer pays, the payment provider notifies your backend, the backend creates a key, sends it to the customer and stores the license ID on the order.

Setup

1. Create a key with the Store preset, tick the right app in Limit to apps and enter the store server's IP.
2. Store the key in the CLAVIS_API_KEY environment variable on the server. Never put the key in code that runs in a browser or in software you ship to customers.
3. Get the App ID app_… from the app's Overview page, or call GET /seller/v1/apps.
4. Pick a license plan. Leaving out policyId uses the app's default plan. The dashboard does not show plan IDs yet; to get the pol_… of another plan, create a key with that plan at Licensing & releases › Licenses, then look that key up with POST /seller/v1/licenses/lookup: the response includes policyId.

Creating a key with curl

curl -X POST https://api.example.com/seller/v1/apps/app_…/licenses \
  -H "Authorization: Bearer $CLAVIS_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"policyId": "pol_…", "count": 1, "email": "buyer@example.com", "note": "Order 1042", "metadata": {"orderId": "1042"}}'

Success returns 201, with keys and ids in the same order:

{
  "data": {
    "keys": ["PRO-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"],
    "ids": ["lic_…"],
    "warnings": []
  }
}

The same thing in JavaScript

The code below runs on Node.js 18 or later. The clavis function sends the key, adds Idempotency-Key and retries on 429, 5xx errors or idempotency_in_progress:

const API = "https://api.example.com/seller/v1";
const APP_ID = "app_…";

async function clavis(path, { method = "GET", body, idempotencyKey } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(API + path, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.CLAVIS_API_KEY}`,
        ...(body ? { "Content-Type": "application/json" } : {}),
        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (res.status === 204) return null;
    const json = await res.json();
    if (res.ok) return json;
    const retry = res.status === 429 || res.status >= 500 || json.error?.code === "idempotency_in_progress";
    if (!retry || attempt === 3) {
      throw new Error(`${json.error?.code}: ${json.error?.message} (requestId ${json.error?.requestId})`);
    }
    const wait = res.status === 429 ? Number(res.headers.get("RateLimit-Reset") ?? 1) : 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
}

// Call when the payment provider confirms the order is paid
export async function fulfilOrder(order) {
  const { data } = await clavis(`/apps/${APP_ID}/licenses`, {
    method: "POST",
    idempotencyKey: `order-${order.id}`,
    body: {
      policyId: order.policyId,
      count: 1,
      email: order.email,
      note: `Order ${order.id}`,
      metadata: { orderId: String(order.id) },
    },
  });
  if (data.warnings.length) console.warn("Clavis:", data.warnings);
  return { licenseId: data.ids[0], key: data.keys[0] };
}

// Refund: revoke the key
export async function refundOrder(order) {
  await clavis(`/licenses/${order.licenseId}/actions`, {
    method: "POST",
    idempotencyKey: `refund-${order.id}`,
    body: { action: "revoke" },
  });
}

// Renew for 30 days, one Idempotency-Key per renewal
export async function renewLicense(licenseId, renewalId) {
  await clavis(`/licenses/${licenseId}/actions`, {
    method: "POST",
    idempotencyKey: `renew-${renewalId}`,
    body: { action: "extend", seconds: 30 * 86400 },
  });
}

Common errors when selling

• unknown_policy (400): the policyId does not belong to this app.
• plan_limit: the batch is over "Keys per batch" or the device count is over "Devices per key" (400), or the daily key limit is used up on Basic (402). On Premium the keys are still created and warnings contains daily_key_limit_exceeded. See Basic, Premium and limits.
• validation_failed (400): the body does not match the schema; details names the field.

Looking up and acting on a license

A support bot or your own admin page usually starts from the key a customer sends you:

curl -X POST https://api.example.com/seller/v1/licenses/lookup \
  -H "Authorization: Bearer $CLAVIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "PRO-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"}'

• The key goes in the body, never in the URL. The server compares hashes, ignoring case and extra spaces; no match returns 404 not_found.
• Send {"mark": "0123456789.abcdef"} instead of a key to find the license behind a buyer mark (Forensic Watermarking). The answer adds markDevice (id, name, platform, active) when the mark's second half matches a machine's current device key, otherwise null.
• The license returned has id, preview, status, maxDevices, devices (machines holding a seat), activatedAt, expiresAt, note, email, policyId and appId. status is the effective status: an active key past its expiry comes back as expired.
• GET /seller/v1/licenses/{id} also returns policy (id, name, entitlements) and metadata.
• GET /seller/v1/apps/{appId}/licenses filters by status (unused, active, expired, suspended, revoked), policyId and q (partial match on note or email, case-insensitive).

Actions use POST /seller/v1/licenses/{id}/actions and return the license after the change:

DELETE /seller/v1/licenses/{id} deletes a key: it is revoked, every session ends, it disappears from lists, and the API returns 204. To remove a single machine instead of the whole key, use POST /seller/v1/devices/{id}/actions with {"action": "revoke"} (scope devices:write); this removal is recorded as done by the seller and does not use up the customer's transfers.

Request log

On every key row, revoked keys included, click the Request log icon to open the Request log panel:

• The 50 most recent calls, newest first, refreshed every 10 seconds.
• Each row shows the method, the path (without the query string), the status code (red from 400 up) and the processing time in ms.
• Only calls that passed the key, IP and rate limit checks are logged. Calls refused with key_in_url, unauthorized, ip_not_allowed or rate_limited do not appear; if an integration fails and the log is empty, check those causes first.

The full list of endpoints, error codes and the OpenAPI document (GET /seller/v1/openapi.json) is in the Seller API reference.

Related

• Creating and managing licenses
• Webhooks
• Resellers and credit
• Basic, Premium and limits