本页暂无中文版本,以下是英文原文。
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/v1Requests 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
| Endpoints | Credential |
|---|---|
/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/verify | None. 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/accept | None. 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:
admincan call everything under/admin, the same as an admin in the dashboard. Webhooks, API keys, products, plans and settings need this scope.licenses:writecan 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:writecan 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:
{ "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:
| Status | What to do |
|---|---|
| 429 | Back 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. |
| 502 | Keygate 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. |
| 503 | FULFILLMENT_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. |
| 500 | INTERNAL_ERROR or EMAIL_QUEUE_FAILED. Worth one retry. The details are in the server log. |
| Other 4xx | The 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:
| Code | Status | Meaning |
|---|---|---|
LICENSE_NOT_FOUND | 404 | No usable license for this key and request. See brute force protection below. |
ACTIVATION_LIMIT | 409 | Every device slot on the license is taken. |
FLOATING_LICENSE | 409 | Activate or verify was called on a floating plan. Check out a seat with /license/floating/checkout instead. |
FLOATING_LIMIT | 409 | Every floating seat is in use. |
SEAT_PAUSED | 403 | Activate 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_HELD | 409 | A member's key tried to activate a device that another key on the license activated. |
SESSION_HELD | 409 | Floating checkout with a member's key on a machine whose running session another key on the license took. |
FEATURE_NOT_AVAILABLE | 404 | The endpoint does not apply to this type of product, for example device activation on a SaaS product. |
LICENSE_EXPIRED, LICENSE_SUSPENDED, ... | 403 | Activate says why a license it found cannot be used. |
QUOTA_EXCEEDED | 429 | The usage quota is spent. details has used, limit and period. |
NO_QUOTA | 400 | Usage was recorded for a feature the plan has no quota for. Reading it with /license/usage/status answers 404 QUOTA_NOT_FOUND. |
LOCKED_OUT | 429 | Too many failed license calls from this address. |
SEAT_LIMIT | 409 | Every 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_USE | 409 | A 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_USE | 409 | The 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_MISMATCH | 403 | A product bound API key reached for another product. |
ADDON_PRODUCT_MISMATCH | 400 | The addon belongs to a different product from the license. |
DUPLICATE | 409 | A slug, or a feature on a plan, is already taken. Sent by create and update alike. |
STRIPE_NOT_CONFIGURED | 503 | The action needs Stripe and this install has no Stripe key. |
STRIPE_UNAVAILABLE | 502 | Stripe did not confirm the change. Nothing was changed; try again. |
SIGNUP_LIMIT_REACHED | 429 | The 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_OUTorQUOTA_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.
| Code | Status | Meaning |
|---|---|---|
IDEMPOTENCY_IN_FLIGHT | 409 | The first request is still running. Retry after the one second its Retry-After asks for. |
IDEMPOTENCY_KEY_CONFLICT | 422 | The same key was used with a different body. |
INVALID_IDEMPOTENCY_KEY | 400 | The 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.
| Endpoint | Purpose | Guide |
|---|---|---|
/license/activate | Register a device or user on a license. | Activating |
/license/verify | Check a license and get a fresh offline token. | Verifying |
/license/deactivate | Free a device or user. | Deactivating |
GET /license/pubkey | The Ed25519 key that verifies offline tokens. | Working offline |
/license/entitlements | The plan's features and remaining quotas. | Features |
/license/usage | Record usage of a metered feature. | Usage |
/license/usage/status | Read a quota without changing it. | Usage |
/license/floating/checkout | Take a floating seat. | Floating |
/license/floating/heartbeat | Keep a floating seat. | Floating |
/license/floating/checkin | Give a floating seat back. | Floating |
/license/download | A 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
identifieris trimmed. Blank, or longer than 256 bytes, answers 400. This applies to activate, verify, deactivate and the three floating endpoints.identifier_typeon activate isdeviceoruser, anddevicewhen left out. Anything else answers 400.labelon activate and floating checkout is trimmed and may be up to 256 characters.quantityon 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
| Endpoint | Returns |
|---|---|
GET /releases/:slug/feed.xml | A Sparkle appcast. |
GET /releases/:slug/velopack/:platform/releases.:channel.json | A Velopack feed. Velopack is given the base address and builds this one. |
GET /releases/:slug/upgrade.json | A 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.
| Endpoint | Purpose |
|---|---|
POST /auth/otp/send | Mail 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/verify | Check the code and start a session. A code allows five guesses, then a new one is needed. |
GET /products/:slug/plans | The 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_id | What the sign up form shows for a self sign up plan, or 404 SIGNUP_UNAVAILABLE. |
POST /signup/:checkout_id/send | Mail a login code to email, with the same limits as /auth/otp/send. |
POST /signup/:checkout_id/verify | Claim 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/accept | Join 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:
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/refundis 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 configured503 STRIPE_NOT_CONFIGURED, and when Stripe does not confirm the cancel502 STRIPE_UNAVAILABLEwith 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 is409 LICENSE_CHANGED. Make the refund itself in Stripe.POST /admin/licenses/:id/addonsanswers 201 when it attaches the addon and 200 with the existing attachment when it was attached already. An addon of another product answers400 ADDON_PRODUCT_MISMATCH, and an unknown one 404.POST /admin/licenses/:id/rotate-keyreissues the license key. The old key stops working at once, the devices and floating sessions activated with it are removed (alicense.deactivatedwebhook for each device), and members keep their own keys and devices. The answer carries the newlicense_keyanddevices_removed. The customer is not told;POST /admin/licenses/:id/resend-emailmails them the key.GET /admin/licenses/:id/seatslists 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/keyreveals a member's key,POST /admin/licenses/:id/seats/:seat_id/rotate-keyreissues it, andDELETE /admin/licenses/:id/seats/:seat_idremoves the member or cancels the invitation, revoking the key and removing its devices. A seat whose invitation was not accepted has no key and answers409 SEAT_NOT_JOINEDto the key routes.POST /admin/licenses/:id/quantitywith{"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 answer409 STRIPE_MANAGED; a plan not sold per seat answers409 NOT_PER_SEAT; a number outside the plan's range answers409 QUANTITY_OUT_OF_RANGE; and going below the people or devices in use answers409 SEATS_IN_USEor409 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_USEinstead. - Webhook endpoints accept only the event names listed under Webhooks; any other name answers 400.
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.
最后更新 2026年10月27日