Documentation menu▾

API reference

Endpoints, authentication, responses, error codes such as SEAT_PAUSED and DEVICE_HELD, idempotency and retries for the Keygate license API and admin API.

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 with their UTC offset, and an empty list is always [], never null. The checkout link /pay/:checkout_id is the one public address outside /api/v1.

Authentication

EndpointsCredential
/license/*None. The license key in the request body is the credential.
/releases/*None, unless the product requires a license on its feed. Then the updater sends the key in an X-License-Key header, or the signed token from verify.
/config, /license/pubkey, /products/:slug/plans, /checkout/verifyNone. These are public.
/auth/*, /signup/*None. The login code mailed to the address proves who the caller is, and a correct code starts a session.
/invites/acceptNone. The token from the invitation email is the credential.
/admin/*An API key, Authorization: Bearer kg_live_..., or a signed in admin's session.
/portal/*A signed in customer's session cookie.

API key scopes

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

  • admin can call everything under /admin, the same as an admin in the dashboard. Webhooks, API keys, products, plans and settings need this scope.
  • licenses:write can list, export, create and read licenses and run their lifecycle actions, such as suspend, revoke, change plan, set an end date, set the seats bought or reissue a key, plus their usage, members, addons, floating sessions and activations. This is what a billing backend needs.
  • releases:write can create, upload, publish, pull and delete releases, for CI.

A key with no scope can do nothing and gets 403 INSUFFICIENT_SCOPE. A key that does not exist or was deleted gets 401 INVALID_API_KEY.

A licenses:write or releases:write key can also be bound to one product. It is then held to that product on every route it can reach: license and release lists, and the license export, return only that product's rows even when no product_id is given, and naming another product, or a license or release that belongs to one, answers 403 PRODUCT_SCOPE_MISMATCH. An admin key always spans every product, because it manages keys and settings for all of them, so it cannot be bound: creating one with a product_id answers 400. Admin keys that carried a product are unbound when the database is migrated.

Responses

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

json
{ "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. The status tells you whether a retry can help:

StatusWhat to do
429Back off and retry after the Retry-After header, in seconds. LOCKED_OUT sends the rest of the lockout (also in details.retry_after), RATE_LIMITED from sending login codes sends 600, and the other rate limits send their whole window, usually 60. Two codes do not clear by retrying soon: QUOTA_EXCEEDED lasts until the quota period resets, and SIGNUP_LIMIT_REACHED until midnight UTC, which its Retry-After counts down to.
502Keygate could not get an answer from a service it depends on. For STRIPE_UNAVAILABLE nothing was changed and the same request can be sent again. EMAIL_SEND_FAILED means the mail server refused a test email; check the email settings.
503FULFILLMENT_RETRY clears on its own, so retry it. The rest point to the setup of the install and will not change until an admin fixes it: codes ending in _NOT_CONFIGURED or _DISABLED mean the feature is turned off, and PLAN_UNAVAILABLE, UPGRADE_UNAVAILABLE and RENEWAL_UNAVAILABLE mean the plan's price in Stripe cannot be sold as configured. LICENSE_KEY_UNAVAILABLE, EXPIRY_NOT_AVAILABLE and METERED_SYNC_NOT_AVAILABLE are the same kind.
500INTERNAL_ERROR or EMAIL_QUEUE_FAILED. Worth one retry. The details are in the server log.
Other 4xxThe request itself is the problem. Retrying it unchanged will not help. This includes the 409s SMTP_NOT_CONFIGURED and SIGNING_NOT_CONFIGURED.

The codes your code is most likely to branch on:

CodeStatusMeaning
LICENSE_NOT_FOUND404No usable license for this key and request. See brute force protection below.
ACTIVATION_LIMIT409Every device slot on the license is taken.
FLOATING_LICENSE409Activate or verify was called on a floating plan. Check out a seat with /license/floating/checkout instead.
FLOATING_LIMIT409Every floating seat is in use.
SEAT_PAUSED403Activate was called with the key of a team member who is paused, because the license holds more people than seats. Verify answers 404 LICENSE_NOT_FOUND for the same key.
DEVICE_HELD409A member's key tried to activate a device that another key on the license activated.
SESSION_HELD409Floating checkout with a member's key on a machine whose running session another key on the license took.
FEATURE_NOT_AVAILABLE404The endpoint does not apply to this type of product, for example device activation on a SaaS product.
LICENSE_EXPIRED, LICENSE_SUSPENDED, ...403Activate says why a license it found cannot be used.
QUOTA_EXCEEDED429The usage quota is spent. details has used, limit and period.
NO_QUOTA400Usage was recorded for a feature the plan has no quota for. Reading it with /license/usage/status answers 404 QUOTA_NOT_FOUND.
LOCKED_OUT429Too many failed license calls from this address.
SEAT_LIMIT409Every seat on the license is taken: when inviting someone (details has max and current, both counting the owner), or when accepting an invitation after the limit went down. The invitation stays valid.
SEATS_IN_USE, DEVICES_IN_USE409A change of plan or of the seats bought would leave fewer seats than people, or fewer devices than are activated. Nothing is removed by a change, so free the room first. details has in_use and seat_limit or activation_limit.
TRIAL_FALLBACK_IN_USE409The plan is the fallback of one or more trial plans, named in details.plans, so it cannot be deleted, made a trial or given a price, update period or renewals.
PRODUCT_SCOPE_MISMATCH403A product bound API key reached for another product.
ADDON_PRODUCT_MISMATCH400The addon belongs to a different product from the license.
DUPLICATE409A slug, or a feature on a plan, is already taken. Sent by create and update alike.
STRIPE_NOT_CONFIGURED503The action needs Stripe and this install has no Stripe key.
STRIPE_UNAVAILABLE502Stripe did not confirm the change. Nothing was changed; try again.
SIGNUP_LIMIT_REACHED429The plan has taken all the self sign ups it accepts today.

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.

  • Keys are shared by everyone who calls the same endpoint, so make each one a fresh random value, such as a UUID, rather than something like the license key.
  • Successful answers and 4xx answers are both stored and replayed. That includes a 429 LOCKED_OUT or QUOTA_EXCEEDED, so once you have waited, send the request with a new key. Change the key whenever you change the request.
  • 5xx answers are not stored, so a retry after a 500 runs the request again.
  • The body may be at most 256 KiB when the header is sent; a larger one answers 413 BODY_TOO_LARGE.
CodeStatusMeaning
IDEMPOTENCY_IN_FLIGHT409The first request is still running. Retry after the one second its Retry-After asks for.
IDEMPOTENCY_KEY_CONFLICT422The same key was used with a different body.
INVALID_IDEMPOTENCY_KEY400The key is longer than 256 bytes or contains a line break or a NUL character.

License API

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

EndpointPurposeGuide
/license/activateRegister a device or user on a license.Activating
/license/verifyCheck a license and get a fresh offline token.Verifying
/license/deactivateFree a device or user.Deactivating
GET /license/pubkeyThe Ed25519 key that verifies offline tokens.Working offline
/license/entitlementsThe plan's features and remaining quotas.Features
/license/usageRecord usage of a metered feature.Usage
/license/usage/statusRead a quota without changing it.Usage
/license/floating/checkoutTake a floating seat.Floating
/license/floating/heartbeatKeep a floating seat.Floating
/license/floating/checkinGive a floating seat back.Floating
/license/downloadA short lived download link for a release.Downloads

Member keys

Every accepted member of a team license has a license key of their own, which works on all of these endpoints and opens the same license. It acts only on the member's own devices and floating sessions: verify, deactivate, heartbeat and checkin with it answer as for an unknown device or session when the device is someone else's, and activate or checkout on a device another key holds answers 409 DEVICE_HELD or 409 SESSION_HELD. The license's own key acts on every device and session. A member who is paused because the license holds more people than seats gets 403 SEAT_PAUSED from activate and 404 LICENSE_NOT_FOUND from the others, deactivate excepted. See member license keys in your app.

Input rules

  • identifier is trimmed. Blank, or longer than 256 bytes, answers 400. This applies to activate, verify, deactivate and the three floating endpoints.
  • identifier_type on activate is device or user, and device when left out. Anything else answers 400.
  • label on activate and floating checkout is trimmed and may be up to 256 characters.
  • quantity on usage counts as 1 when it is 0 or left out. A negative quantity answers 400.
  • Activate and verify on a license whose plan is floating answer 409 FLOATING_LICENSE, also for a device activated on it before. Deactivate still works.

Brute force protection

Failed activate, verify and deactivate calls are counted per IP address: a key that does not exist, a key of another product, and verify on a license that cannot be used or with the key of a paused member. After five failures within five minutes, that address is locked out of every /license endpoint and receives 429 LOCKED_OUT: for 30 seconds the first time, then twice as long each time, up to 30 minutes. The doubling is remembered until 30 minutes after the last lockout ends, and a successful call from the address clears it.

Verify answers 404 LICENSE_NOT_FOUND whether the key does not exist, belongs to another product, is suspended, revoked or expired, belongs to a paused member, or was never activated on this device by this key, so a valid key cannot be found by watching its responses. Deactivate answers the same for a key or device it does not know. Activate is different on purpose: it tells a real customer why their license cannot be used, with codes such as 403 LICENSE_EXPIRED or 403 SEAT_PAUSED.

Update feeds

EndpointReturns
GET /releases/:slug/feed.xmlA Sparkle appcast.
GET /releases/:slug/velopack/:platform/releases.:channel.jsonA Velopack feed. Velopack is given the base address and builds this one.
GET /releases/:slug/upgrade.jsonA Tauri update manifest for the newest release, or 204 when the channel has no release for the platform, or none inside the license's update period.

The Sparkle and Tauri feeds take platform (required), channel (stable when left out) and, for Sparkle, limit (1 to 100). The Velopack address carries both in its path: the platform after velopack/ and the channel in the file name, unless a channel parameter is added. Keygate does not see the version the app runs; Tauri compares the manifest's version with its own and installs only a newer one. See Shipping updates.

Sign in, sign up and checkout

The portal, the sign up form and the checkout pages use these public endpoints. You only call them yourself if you build your own pages.

EndpointPurpose
POST /auth/otp/sendMail a six digit login code. Each address gets three codes every ten minutes; the fourth request answers 429 RATE_LIMITED with Retry-After: 600.
POST /auth/otp/verifyCheck the code and start a session. A code allows five guesses, then a new one is needed.
GET /products/:slug/plansThe product's active plans for a pricing page, with price, currency, checkout ID and whether the plan takes self sign ups. A plan sold per seat has per_seat: true, a price per seat, and min_quantity and max_quantity.
GET /signup/:checkout_idWhat the sign up form shows for a self sign up plan, or 404 SIGNUP_UNAVAILABLE.
POST /signup/:checkout_id/sendMail a login code to email, with the same limits as /auth/otp/send.
POST /signup/:checkout_id/verifyClaim the license with email and code, plus marketing_consent and the consent_text the form showed. Answers 201 with status: created, or 200 with status: existing when the address already claimed one for this product. Either way the visitor is signed in.
POST /invites/acceptJoin a license as a team member with the token from the invitation email. A token that is unknown, expired, already used or removed, or a license that cannot be used, all answer the same 404 SEAT_INVITE_INVALID. When no seat is free it answers 409 SEAT_LIMIT instead, with nothing changed, and the invitation stays valid until it expires.
GET /checkout/verify?session_id=Used by the page Stripe returns to. status is ok, pending while the payment or license is still on its way, or not_applied for an upgrade that was refunded or whose subscription ended before it could be applied.

See self sign up for how a plan opens its sign up form. The checkout link /pay/:checkout_id of a plan sold per seat takes ?quantity=, the number of seats Stripe Checkout starts with (the plan's min_quantity when left out). The buyer can change it on Stripe's page within the plan's range. A quantity outside that range, or above 1 on a plan not sold per seat, answers 400.

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:

bash
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.

  • POST /admin/licenses/:id/refund is the dashboard's Cancel and revoke, and it moves no money. It cancels the license's Stripe subscription first and only then changes the license: a license that an upgrade moved onto that subscription goes back to its free plan, answering {"status": "reverted_to_free_plan"}; any other is revoked, answering {"status": "refunded"}. Without a subscription it answers 400, without Stripe configured 503 STRIPE_NOT_CONFIGURED, and when Stripe does not confirm the cancel 502 STRIPE_UNAVAILABLE with the license unchanged. If the license left the subscription meanwhile (a Stripe event put it back on its free plan at the same moment), it is not revoked and the answer is 409 LICENSE_CHANGED. Make the refund itself in Stripe.
  • POST /admin/licenses/:id/addons answers 201 when it attaches the addon and 200 with the existing attachment when it was attached already. An addon of another product answers 400 ADDON_PRODUCT_MISMATCH, and an unknown one 404.
  • POST /admin/licenses/:id/rotate-key reissues the license key. The old key stops working at once, the devices and floating sessions activated with it are removed (a license.deactivated webhook for each device), and members keep their own keys and devices. The answer carries the new license_key and devices_removed. The customer is not told; POST /admin/licenses/:id/resend-email mails them the key.
  • GET /admin/licenses/:id/seats lists the license's members and pending invitations, each with the prefix and last four characters of the member's own key and how many devices it activated. GET /admin/licenses/:id/seats/:seat_id/key reveals a member's key, POST /admin/licenses/:id/seats/:seat_id/rotate-key reissues it, and DELETE /admin/licenses/:id/seats/:seat_id removes the member or cancels the invitation, revoking the key and removing its devices. A seat whose invitation was not accepted has no key and answers 409 SEAT_NOT_JOINED to the key routes.
  • POST /admin/licenses/:id/quantity with {"quantity": 5} sets the seats of a license on a plan sold per seat that Stripe does not bill, such as a sale made outside Stripe. A Stripe subscription's seats come from Stripe and answer 409 STRIPE_MANAGED; a plan not sold per seat answers 409 NOT_PER_SEAT; a number outside the plan's range answers 409 QUANTITY_OUT_OF_RANGE; and going below the people or devices in use answers 409 SEATS_IN_USE or 409 DEVICES_IN_USE.
  • Deleting a product, plan, entitlement, addon, API key, webhook or a license's addon answers 204, or 404 when there was nothing to delete. A plan that trial plans fall back to answers 409 TRIAL_FALLBACK_IN_USE instead.
  • Webhook endpoints accept only the event names listed under Webhooks; any other name answers 400.

Pagination

Admin lists are paginated with limit and offset:

json
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.

Last updated October 27, 2026