Software Licenses Manager API - Quick start

Base URL: https://api.xp-flightdeck.com/licenses-api/v1

What this API does

Issue and validate short-lived license tokens tied to an end user's email and device. This API is multi-publisher: each publisher (game studio, SaaS, software vendor) has its own tokens and only ever sees its own data. Publisher admins can create licenses, list them, enable/disable, and deactivate devices — all scoped to their own account.

Authentication

Every request must include the header matching its tier — each publisher's tokens are unique to them, generated once when their account is created: - Client endpoints: X-Client-Token: <token> — your publisher's client token - Admin endpoints: X-Admin-Token: <token> — your publisher's admin token - Platform endpoints: X-Platform-Token: <token> — operator-only, provisions publisher accounts

On failure you’ll receive 401 {"detail":"invalid client/admin/platform token"}.

Key concepts

• License key format: XXXX-XXXX-XXXX (A–Z without O/I, digits 2–9).
• Device binding: Activations are stored per device_hash + device_name.
• Quota: Each license enforces max_activations per end user; a new device beyond the quota returns 409 with counts.
• Rate limiting: /activate is throttled per (publisher, email) — a 429 means too many attempts for that specific end user, not the whole publisher.
• Short-lived token: /activate returns a JSON payload + Ed25519 signature (sig) + a key id (kid). Use /public-keys to verify.
• Key rotation: the signing key can be rotated by the platform operator without invalidating tokens already in flight — always look up the public key matching the token's kid, don't hardcode a single key.

Token structure (returned by /activate)

{
  "token": {
    "publisher": "your-publisher-slug",
    "kid": "a1b2c3d4",
    "product": "YourProduct",
    "edition": "Pro",
    "features": ["featA", "featB"],
    "license_ref": "GH45",
    "email": "pilot@example.com",
    "max_activations": 3,
    "activations_count": 1,
    "issued_at": "2025-09-01T10:00:00+00:00",
    "expires_at": "2025-09-01T11:00:00+00:00",
    "device": { "hash": "sha256-of-device", "name": "My PC" },
    "sig": "base64-ed25519-signature"
  },
  "mode": "full"
}

• Verify the token by fetching GET /public-keys, picking the entry whose kid matches the token's kid, and verifying the signature over the UTF-8 JSON bytes of the token payload (without the sig field). Optionally also assert token.publisher matches your own slug — the signing key is shared platform-wide, so the signature alone only proves authenticity, not that the token was meant for you.

Quickstart cURL (client)

Activate (required fields: email, license_key, device_hash, device_name):

curl -sS -X POST   -H "X-Client-Token: $CLIENT_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/activate   -d '{
        "email":"pilot@example.com",
        "license_key":"ABCD-EF23-GH45",
        "device_hash":"<sha256>",
        "device_name":"My PC"
      }'

Deactivate (required: license_key_hash, device_hash):

curl -sS -X POST   -H "X-Client-Token: $CLIENT_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/deactivate   -d '{
        "license_key_hash":"<64-hex>",
        "device_hash":"<sha256>"
      }'

Quickstart cURL (admin)

Create license (required: email, product, edition, max_activations; optional: features):

curl -sS -X POST   -H "X-Admin-Token: $ADMIN_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/admin/licenses   -d '{
        "email":"pilot@example.com",
        "product":"YourProduct",
        "edition":"Pro",
        "max_activations":3,
        "features":["featA","featB"]
      }'

List licenses (all query params optional: email, product, edition, enabled, limit, offset; response is { items, total }):

curl -sS   -H "X-Admin-Token: $ADMIN_TOKEN"   "https://api.xp-flightdeck.com/licenses-api/v1/admin/licenses?email=pilot@example.com&enabled=true&limit=50&offset=0"

Enable/disable (required: license_key, enabled, email):

curl -sS -X POST   -H "X-Admin-Token: $ADMIN_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/admin/licenses/enable   -d '{
        "license_key":"ABCD-EF23-GH45",
        "enabled":true,
        "email":"pilot@example.com"
      }'

Force deactivate device (required: license_key, device_hash, email):

curl -sS -X POST   -H "X-Admin-Token: $ADMIN_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/admin/deactivate-device   -d '{
        "license_key":"ABCD-EF23-GH45",
        "device_hash":"<sha256>",
        "email":"pilot@example.com"
      }'

Quickstart cURL (platform — operator only)

Create a publisher (required: name, slug; returns client_token/admin_token once):

curl -sS -X POST   -H "X-Platform-Token: $PLATFORM_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/platform/publishers   -d '{
        "name":"Your Studio",
        "slug":"your-studio"
      }'

Rotate a publisher token (required: slug, which: client or admin):

curl -sS -X POST   -H "X-Platform-Token: $PLATFORM_TOKEN"   -H "Content-Type: application/json"   https://api.xp-flightdeck.com/licenses-api/v1/platform/publishers/rotate-token   -d '{
        "slug":"your-studio",
        "which":"client"
      }'