API reference

This page describes the rules every endpoint follows and lists the endpoints your app and your servers will use. The full machine readable description of the license API is the OpenAPI file in the repository, which you can load into Postman, Insomnia or a client generator.

Base URL#

All endpoints live under your install's address:

https://licenses.example.com/api/v1

Requests and responses are JSON. Field names are snake_case, timestamps are RFC 3339 in UTC, and an empty list is always [], never null.

Authentication#

Create API keys under API Keys in the dashboard and give each one only the scope it needs:

• admin can do everything an admin can do in the dashboard.
• licenses:write can create licenses and manage their lifecycle, which is what a billing backend needs.
• releases:write can upload and publish releases, for CI.

A key can also be limited to one product; reaching for another product's data then answers 403 PRODUCT_SCOPE_MISMATCH. A key with no scope can do nothing.

Responses#

Every response has the same shape, whether it succeeds or not:

{ "success": true,  "data": { ... } }
{ "success": false, "error": { "code": "LICENSE_NOT_FOUND", "message": "license not found" } }

Exactly one of data and error is present. A few error codes add a details object, for example ACTIVATION_LIMIT includes {"current": 3, "max": 3}. The update feeds are the exception to the envelope: they return the format the updater expects when they succeed.

Errors and retries#

Each error code always comes with the same HTTP status, so you can branch on the code and decide whether to retry from the status:

Idempotency#

Three endpoints accept an Idempotency-Key header: activate, usage and floating checkout. Send the same key with every retry of one request. A retry gets the first response back, marked with an Idempotent-Replayed: true header, for 24 hours.

License API#

Called by your app. All are POST with a JSON body containing at least license_key, except pubkey.

Brute force protection

Failed license calls are counted per IP address. After five failures within five minutes, that address is locked out and receives 429 LOCKED_OUT: for 30 seconds the first time, then twice as long each time, up to 30 minutes. Verify answers 404 LICENSE_NOT_FOUND for every kind of failure, so a valid key cannot be found by watching the responses.

Update feeds#

All three take platform (required), channel and, for the first two, limit. See Shipping updates.

Admin API#

Everything the dashboard does goes through the admin API, so anything you can click you can also automate. The most common job is creating a license from your own backend, for example when a sale happens outside Stripe:

curl -X POST https://licenses.example.com/api/v1/admin/licenses \
  -H "Authorization: Bearer kg_live_..." \
  -H "Content-Type: application/json" \
  -d '{"product_id":"...","plan_id":"...","email":"[email protected]",
       "external_customer_id":"cus_1042"}'

external_customer_id is optional and links the license to the customer in your own system. Find the licenses for that customer again with GET /admin/licenses?external_customer_id=cus_1042. Licenses are suspended, reinstated and revoked with POST /admin/licenses/:id/suspend, /reinstate and /revoke.

Pagination#

Admin lists are paginated with limit and offset:

GET /api/v1/admin/licenses?limit=50&offset=0

{ "success": true, "data": {
    "licenses": [ ... ],
    "total": 1234,
    "limit": 50,
    "offset": 0 } }

The default page size is 50 and the largest is 200. Asking for more is not an error; you get 200, and the limit in the answer says so. Always work out the number of pages from the response, not from what you asked for.