Here's the doc

[j2l]

Problem

No doc for humans 😄

Note: The (partially generated) doc below might have mistakes.

Proposed solution

Overview

Keygate is a license management API for software products. This document covers the public SDK endpoints and portal endpoints. The API uses a consistent JSON envelope for all responses.

Base URL: {server}/api/v1

Install

(see in readme)

First Admin run

Into the .env:

• Add an admin email into ADMIN_EMAILS
• If no SMTP is set up, validation code is in your keygate container's logs.

docker compose up -d
Visit http://localhost:9000
Create a product (desktop, saas or hybrid).
Create a plan for the product.
In another browser, register a test customer (needs working SMTP settings in your .env)
Back into the admin:
check for the customer
Issue a new license for this customer

Customer Example Workflow

SDK Integration (Mobile App)

First Customer Run:

    # Get public key
    curl https://your-server.com/api/v1/license/pubkey
    # Save the public_key for offline verification

Activation:

    curl -X POST https://your-server.com/api/v1/license/activate \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: my-unique-id" \
      -d '{
        "license_key": "KG-...",
        "identifier": "device-uuid",
        "label": "iPhone 15"
      }'

On Each Launch:

    curl -X POST https://your-server.com/api/v1/license/verify \
      -H "Content-Type: application/json" \
      -d '{
        "license_key": "KG-...",
        "identifier": "device-uuid"
      }'
    # Verify the returned token offline using saved public key

Usage Recording:

    curl -X POST https://your-server.com/api/v1/license/usage \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: usage-20260820-001" \
      -d '{
        "license_key": "KG-...",
        "feature": "api_calls",
        "quantity": 1
      }'

Floating License

Checkout:

    curl -X POST https://your-server.com/api/v1/license/floating/checkout \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: checkout-001" \
      -d '{
        "license_key": "KG-...",
        "identifier": "engineering-01",
        "label": "Engineer Workstation"
      }'

Heartbeat every 15 minutes:

    curl -X POST https://your-server.com/api/v1/license/floating/heartbeat \
      -H "Content-Type: application/json" \
      -d '{
        "license_key": "KG-...",
        "identifier": "engineering-01"
      }'

Checkin when done:

    curl -X POST https://your-server.com/api/v1/license/floating/checkin \
      -H "Content-Type: application/json" \
      -d '{
        "license_key": "KG-...",
        "identifier": "engineering-01"
      }'

---

Authentication & Security

SDK Public Endpoints

Public SDK endpoints (/license/*, /releases/:slug/feed.*) do NOT require an API key. The license_key in the request body is the credential. Stable release feeds are fully public — trust comes from the per-product Ed25519 signature on each artifact, not from URL secrecy.

Admin Server-to-Server

For server-to-server admin access (CI/CD, billing backends, automation scripts) use API keys with the admin scope. Pass them as:

text

Authorization: Bearer kg_live_…

Admin keys are equivalent to a logged-in admin session and can call any /admin/* endpoint. Mint them in the admin dashboard under API Keys.

Portal Endpoints

Portal endpoints (/portal/*) require a session cookie issued by /auth/otp/verify, /auth/dev-login, or /invites/accept. The cookie is HttpOnly + SameSite=Lax; browsers attach it automatically.

---

Idempotency

Write endpoints (/license/activate, /license/usage, /license/floating/checkout) honor the Idempotency-Key header:

• Same key + same body: Replays the cached response (200/4xx) within 24 hours

• Same key + different body: Returns 422 IDEMPOTENCY_KEY_CONFLICT

• Concurrent retries while original is still running: Returns 409 IDEMPOTENCY_IN_FLIGHT (retry with backoff)

Replayed idempotent responses carry the header Idempotent-Replayed: true.

---

Response Format

Success Response

json

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response

json

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "...",
    "details": { ... }
  }
}

---

Endpoints

License Management

Get Verification Key

GET /license/pubkey

Returns the Ed25519 public key used to verify offline tokens.

Request Example:

http

GET /api/v1/license/pubkey
Host: your-server.com

Response Example:

json

{
  "success": true,
  "data": {
    "algorithm": "ed25519",
    "format": "hex",
    "public_key": "a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef"
  }
}

---

Activate License

POST /license/activate

Registers a device or user identifier against a license. Returns a signed verification token.

Request Headers:

• Idempotency-Key (optional, string, max 256 chars)

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "identifier": "device-a1b2c3d4",
  "identifier_type": "device",
  "label": "MacBook Pro"
}

Response Example:

json

{
  "success": true,
  "data": {
    "status": "activated",
    "license_id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "eyJhbGciOiJIUzI1NiIsInR...<base64url-payload>.<base64url-signature>"
  }
}

Error Responses:

• 400: Validation failure

• 403: License not usable (expired/suspended/revoked/canceled)

• 404: License not found

• 409: ACTIVATION_LIMIT (slots exhausted) or IDEMPOTENCY_IN_FLIGHT

• 422: IDEMPOTENCY_KEY_CONFLICT

• 429: Brute-force lockout

---

Verify License

POST /license/verify

Checks that a license is valid and the identifier is activated. Returns the license status, plan features, and a signed token.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "identifier": "device-a1b2c3d4"
}

Response Example:

json

{
  "success": true,
  "data": {
    "status": "active",
    "plan_id": "plan_123",
    "plan_name": "Pro",
    "valid_until": "2027-01-01T00:00:00Z",
    "features": {
      "premium_support": true,
      "api_calls": "50000",
      "storage_gb": "100"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR...",
    "grace_days": 0
  }
}

Error Response:

json

{
  "success": false,
  "error": {
    "code": "LICENSE_NOT_FOUND",
    "message": "License not found or invalid",
    "details": null
  }
}

Note: All "license-knowable" failures collapse to 404 LICENSE_NOT_FOUND to prevent probing.

---

Deactivate License

POST /license/deactivate

Removes an activation, freeing a slot for a new device.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "identifier": "device-a1b2c3d4"
}

Response Example:

json

{
  "success": true,
  "data": null
}

Error Response:

json

{
  "success": false,
  "error": {
    "code": "LICENSE_NOT_FOUND",
    "message": "License not found or identifier not activated",
    "details": null
  }
}

---

Entitlements

Check Feature Entitlements

POST /license/entitlements

Returns all features available for the license's plan, including quota usage for metered features.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "feature": "premium_support"  // Optional
}

Response Example:

json

{
  "success": true,
  "data": {
    "licensed": true,
    "status": "active",
    "plan_id": "plan_123",
    "plan_name": "Pro",
    "features": {
      "premium_support": {
        "enabled": true,
        "value_type": "bool",
        "value": "true",
        "used": null,
        "limit": null,
        "remaining": null,
        "period": "lifetime",
        "resets_at": null
      },
      "api_calls": {
        "enabled": true,
        "value_type": "quota",
        "value": "50000",
        "used": 451,
        "limit": 1000,
        "remaining": 549,
        "period": "monthly",
        "resets_at": "2026-04-01T00:00:00Z"
      }
    }
  }
}

---

Usage

Record Usage

POST /license/usage

Increments a usage counter for a metered feature. Atomic — concurrent requests will never exceed the quota.

Request Headers:

• Idempotency-Key (optional)

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "feature": "api_calls",
  "quantity": 5,
  "metadata": {
    "endpoint": "/users",
    "method": "GET"
  }
}

Response Example:

json

{
  "success": true,
  "data": {
    "accepted": true,
    "used": 456,
    "limit": 1000,
    "remaining": 544,
    "period": "monthly",
    "period_key": "2026-03"
  }
}

Error Response:

json

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Usage quota exceeded for api_calls",
    "details": {
      "used": 1000,
      "limit": 1000,
      "period": "monthly"
    }
  }
}

---

Get Quota Status

POST /license/usage/status

Returns current usage and remaining quota for a feature.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "feature": "api_calls"
}

Response Example:

json

{
  "success": true,
  "data": {
    "feature": "api_calls",
    "used": 456,
    "limit": 1000,
    "remaining": 544,
    "period": "monthly",
    "period_key": "2026-03"
  }
}

---

Alternatives considered

No response

[j2l]

Floating Licenses

Checkout Floating Session

POST /license/floating/checkout

Acquires a concurrent session slot. The session expires after the plan's floating_timeout (default 30 minutes) unless refreshed via heartbeat.

Request Headers:

• Idempotency-Key (optional)

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "identifier": "workstation-001",
  "label": "Engineering Workstation"
}

Response Example:

json

{
  "success": true,
  "data": {
    "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "expires_at": "2026-08-20T15:30:00Z",
    "active_sessions": 3,
    "max_sessions": 5
  }
}

---

Release Floating Session

POST /license/floating/checkin

Releases a floating session.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "identifier": "workstation-001"
}

Response Example:

json

{
  "success": true,
  "data": null
}

---

Extend Floating Session (Heartbeat)

POST /license/floating/heartbeat

Refreshes the session expiry. Call periodically to keep the session alive.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "identifier": "workstation-001"
}

Response Example:

json

{
  "success": true,
  "data": null
}

---

Portal Endpoints (Seat Management)

Authentication: These endpoints require a portal session cookie.

List Seats

POST /portal/seats

Returns all team members for a license owned by the authenticated portal user.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456"
}

Response Example:

json

{
  "success": true,
  "data": {
    "seats": [
      {
        "id": "seat_123",
        "email": "team-member@example.com",
        "role": "member",
        "accepted_at": "2026-08-15T10:00:00Z",
        "invited_at": "2026-08-14T09:00:00Z"
      }
    ]
  }
}

Error:

json

{
  "success": false,
  "error": {
    "code": "LICENSE_NOT_FOUND",
    "message": "License not found or not yours",
    "details": null
  }
}

---

Invite Team Member

POST /portal/seats/add

Adds a seat to the license. Only the license owner or an accepted admin seat may call this.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "email": "new-member@example.com",
  "role": "member"
}

Response Example:

json

{
  "success": true,
  "data": {
    "seat_id": "seat_456",
    "email": "new-member@example.com",
    "role": "member",
    "status": "pending",
    "invited_at": "2026-08-20T12:00:00Z"
  }
}

Error Responses:

• 400: Self-invite or invalid role

• 401: Not signed in

• 404: License not found or caller lacks mutation rights

• 409: Seat limit reached (SEAT_LIMIT)

---

Remove Team Member

POST /portal/seats/remove

Soft-removes a seat (sets removed_at). Same auth rules as /portal/seats/add.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "seat_id": "seat_456"
}

Response Example:

json

{
  "success": true,
  "data": null
}

---

Invite Acceptance

Accept Seat Invite

POST /invites/accept

Public endpoint that consumes the plain invite token from the seat-invite email. No prior session is required.

Request Body:

json

{
  "token": "a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef"
}

Response Example:

json

{
  "success": true,
  "data": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "new-member@example.com",
    "license_id": "550e8400-e29b-41d4-a716-446655440001",
    "product_name": "My Product",
    "role": "member"
  }
}

Error Responses:

• 404: SEAT_INVITE_INVALID (invalid, expired, already-used, or removed token)

• 429: Rate limit exceeded

Note: On success, a portal session cookie (Set-Cookie: session=…) is issued.

---

Releases (Downloads & Auto-Updates)

Get License-Gated Download URL

POST /license/download

Returns a short-lived presigned URL for the artifact.

Request Body:

json

{
  "license_key": "KG-ABCD1234-EFGH5678-IJKL9012-MNOP3456",
  "platform": "darwin-arm64",
  "channel": "stable",
  "version": "1.2.3"  // Optional
}

Response Example:

json

{
  "success": true,
  "data": {
    "url": "https://storage.example.com/releases/my-app/v1.2.3/my-app.dmg?Expires=1734567890&Signature=...",
    "expires_at": "2026-08-20T14:00:00Z",
    "version": "1.2.3",
    "platform": "darwin-arm64",
    "sha256": "a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef",
    "file_size": 123456789
  }
}

Error Responses:

• 400: Invalid platform/channel

• 403: License inactive

• 404: License not found or no release matches

• 410: Requested version was yanked

• 503: Storage not configured

---

Public Update Feeds

These endpoints are fully public and do not require authentication. Trust comes from the per-product Ed25519 signature on each artifact.

Sparkle Appcast (macOS)

text

GET /releases/{product_slug}/feed.xml?platform=darwin-arm64&channel=stable&limit=20

Response Example:

xml

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
  <channel>
    <title>My App - Stable</title>
    <item>
      <title>Version 1.2.3</title>
      <pubDate>Wed, 19 Aug 2026 12:00:00 +0000</pubDate>
      <enclosure url="https://storage.example.com/releases/my-app/v1.2.3/my-app.dmg" 
                 sparkle:version="1.2.3" 
                 length="123456789" 
                 type="application/octet-stream"
                 sparkle:edSignature="base64signature"/>
    </item>
  </channel>
</rss>

---

Velopack Feed (Windows)

text

GET /releases/{product_slug}/feed.json?platform=windows-x64&channel=stable&limit=20

Response Example:

json

[
  {
    "Version": "1.2.3",
    "Date": "2026-08-19T12:00:00Z",
    "File": "my-app-v1.2.3-win-x64.exe",
    "Size": 123456789,
    "SHA256": "a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef"
  }
]

---

Tauri Updater Manifest (Cross-Platform)

text

GET /releases/{product_slug}/upgrade.json?platform=darwin-arm64&channel=stable

Response Example:

json

{
  "version": "1.2.3",
  "pub_date": "2026-08-19T12:00:00Z",
  "url": "https://storage.example.com/releases/my-app/v1.2.3/my-app.dmg",
  "signature": "untrusted comment: minisign public key 12345678\nbase64signature==",
  "notes": "Bug fixes and performance improvements",
  "minimum_supported_version": "1.0.0",
  "minimum_supported_message": "Please update your app to continue receiving updates."
}

Note: If no published release exists for the channel/platform, returns 204 No Content.

---

Common Error Codes

Code	Description
LICENSE_NOT_FOUND	License doesn't exist, belongs to another product, wrong device, suspended, revoked, or expired
ACTIVATION_LIMIT	Max activations exceeded
QUOTA_EXCEEDED	Usage quota exceeded for a metered feature
SEAT_LIMIT	Max seats exceeded for the plan
SEAT_INVITE_INVALID	Invalid, expired, already-used, or removed invite token
IDEMPOTENCY_KEY_CONFLICT	Same Idempotency-Key reused with a different body
IDEMPOTENCY_IN_FLIGHT	Concurrent retry in progress
LOCKED_OUT	Brute-force protection lockout

---

Admin API Keys

For server-to-server admin access:

1. Go to the admin dashboard

2. Navigate to API Keys

3. Generate a new key with the admin scope

4. Use it as:

   text

   Authorization: Bearer kg_live_abc123...

Admin keys can call any /admin/* endpoint (not documented in this spec).

---

Security Notes

• Existence Oracle Hardening: /license/verify and /license/deactivate collapse all failure types to 404 LICENSE_NOT_FOUND to prevent attackers from probing valid license keys.

• Brute-Force Protection: Failed activation attempts trigger per-IP exponential lockout (default: 5 failures → 30s lockout).

• Idempotency Keys: Safe retries for write endpoints; cached responses for 24 hours.

• Signed Offline Tokens: Tokens returned by /license/activate and /license/verify are signed with Ed25519; verify offline using the public key from /license/pubkey.

Changelog

v1.1.0: Added portal endpoints, invite acceptance, and release feeds.
v1.0.0: Initial release with license management, entitlements, usage, and floating licenses.