Reference

Vendor API reference

Manage products, plans, licenses, activations, customers, integrations and API keys with a secret key.

The vendor API is what the dashboard uses. Call it from your backend or scripts to create licenses for resellers, look up a customer for support, or automate anything you do in the dashboard.

Authentication#

Create a secret key in the dashboard (API keys → New secret key, see the dashboard guide) or with POST /v1/api-keys. It looks like kr_sk_ followed by 32 characters and is shown once. Keyrail only keeps its SHA-256 hash.

export KEYRAIL_SECRET_KEY="kr_sk_…"

curl https://api.keyrail.tech/v1/account \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY"

Never ship a secret key inside your app: apps use the client API, which needs no secret. Every object you read or write is scoped to the key’s account.

Conventions#

• Base URL https://api.keyrail.tech/v1, JSON in and out, timestamps in ISO 8601 UTC (2026-12-01T00:00:00Z).
• Lists return { "data": [...], "nextCursor": "..." }. Pass cursor=<nextCursor> to get the next page; nextCursor is null on the last one. Pages hold 50 items.
• Errors use the same shape as the client API: { "error": { "code": "...", "message": "..." } }. Extra codes: 401 unauthorized (missing or invalid key), 404 not_found, 409 conflict (any change to a revoked license, a duplicate plan code or integration), 402 plan_limit (creating a product beyond your plan), 429 rate_limited (5,000 requests per hour per account). Every code, with fixes: troubleshooting.
• Response examples on this page are abridged.

Products#

curl https://api.keyrail.tech/v1/products \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Notes", "keyPrefix": "ACME", "graceDays": 14, "offlineDays": 30 }'

{ "id": "prd_7k2m9q4x1c8d3f6h0j5n", "name": "Acme Notes", "keyPrefix": "ACME", "graceDays": 14, "offlineDays": 30, "createdAt": "2026-10-13T09:00:00Z" }

Signing keys#

curl https://api.keyrail.tech/v1/products/prd_7k2m9q4x1c8d3f6h0j5n/keys \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY"

{
  "data": [
    { "kid": "k1", "publicKey": "pZ3vC0x6hYjQ8m1K4tR9wN2bF7sL5dA0eUqTgHiOcVk", "status": "active",
      "createdAt": "2026-10-13T09:00:00Z", "activatedAt": "2026-10-13T09:00:00Z" }
  ],
  "nextCursor": null
}

Private keys are never returned here, nor by the account export: only by the owner-only export route above.

Plans#

Fields: code (lowercase slug, unique per product, 409 conflict otherwise), name (defaults to the code), kind (subscription, perpetual, trial), maxActivations (default 1), entitlements (array of strings), maxMajor (integer or null), trialDays (default 14 for a trial), offlineDays (1 to 365, or null for the product’s value: the default). code and kind cannot change once the plan exists: the code is in certificates and price maps.

curl https://api.keyrail.tech/v1/products/prd_7k2m9q4x1c8d3f6h0j5n/plans \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "pro", "name": "Pro", "kind": "subscription", "maxActivations": 2, "entitlements": ["export", "ocr"], "maxMajor": null }'

A plan’s offlineDays overrides the product’s for the certificates of its licenses; the plan returns null when it has no override.

Licenses#

Create a license for a reseller or a giveaway:

curl https://api.keyrail.tech/v1/licenses \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "pln_5d9h3m7q1t4x8c2f6k0n", "email": "jane@example.com", "name": "Jane Doe", "seats": 1, "paidUntil": "2027-10-13T00:00:00Z" }'

{
  "id": "lic_3n8f2k5m9q1x4c7d0h6j",
  "product": "prd_7k2m9q4x1c8d3f6h0j5n",
  "plan": "pro",
  "planId": "pln_5d9h3m7q1t4x8c2f6k0n",
  "planName": "Pro",
  "customer": { "id": "cus_0j5n3f6h8d1c4x9q2m7k", "email": "jane@example.com", "name": "Jane Doe" },
  "status": "active",
  "seats": 1,
  "maxActivations": null,
  "activationLimit": 2,
  "maxMajor": null,
  "entitlements": ["export", "ocr"],
  "paidUntil": "2027-10-13T00:00:00Z",
  "validUntil": "2027-10-27T00:00:00Z",
  "provider": null,
  "activationCount": 0,
  "createdAt": "2026-10-13T09:00:00Z",
  "updatedAt": "2026-10-13T09:00:00Z",
  "key": "ACME-7K2M9-Q4X1C-8D3F6-H0J5N",
  "activations": []
}

plan is the plan code, as in certificates. maxActivations is the per-license override (null when none) and activationLimit the effective limit. List items have the same fields without key and activations.

Find a customer’s licenses for a support request:

curl "https://api.keyrail.tech/v1/licenses?email=jane@example.com" \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY"

Give a perpetual customer access to version 2 after an upgrade purchase:

curl -X PATCH https://api.keyrail.tech/v1/licenses/lic_3n8f2k5m9q1x4c7d0h6j \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "maxMajor": 2 }'

Suspend a license:

curl -X POST https://api.keyrail.tech/v1/licenses/lic_3n8f2k5m9q1x4c7d0h6j/suspend \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY"

Activations#

curl -X DELETE https://api.keyrail.tech/v1/activations/act_9c4h7k1m5p8r2t6v0x3z \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY"

Customers#

Integrations#

webhookSecret and apiKey are write-only: responses show hasWebhookSecret and hasApiKey instead. The secret can be added after creation, because Paddle only shows it once the notification destination (which needs the webhookUrl) exists; until it is set, every webhook is refused with 401. The Paddle apiKey (read-only customer.read permission is enough) lets Keyrail fetch a customer’s email immediately; see Paddle Billing. priceMap maps a provider price ID (Paddle) or variant ID (Lemon Squeezy) to a plan code: { "pri_01hv8x2monthly000000000000": "pro" }. Responses include the webhookUrl to paste into the provider. Guides: Paddle Billing, Lemon Squeezy.

API keys#

Account and usage#

Export and closure are dashboard actions of the account owner (Account & usage), not available with an API key: Export data downloads everything as JSON (license keys included, secrets excluded). Close account revokes API keys and sessions at once, cancels your Keyrail subscription at the end of the paid period and refuses new activations; machines already activated keep validating for 30 days and your customers' payments keep being applied (renewals extend paidUntil; no license key is e-mailed meanwhile). During those 30 days the dashboard cannot be signed in to (export before closing), and the e-mailed link reopens the account (resuming the subscription when it has not ended); then every piece of data is deleted.

Events#

curl "https://api.keyrail.tech/v1/events?license=lic_3n8f2k5m9q1x4c7d0h6j" \
  -H "Authorization: Bearer $KEYRAIL_SECRET_KEY"

View as Markdown

Need help? See Troubleshooting or write to support@keyrail.tech.