API reference

Every HTTP endpoint on the SDKey Worker, top to bottom.

Conventions

Base URL: https://api.sdkey.dev
Base path: /api/v1 (plus GET /health)
Dashboard auth: cookie sdkey_session (EdDSA JWT, 7 days) or Authorization: Bearer sdk_live_…
Client license path: no developer auth — see License control
Rate limits are per IP per 60s window unless noted

Health

GET/health

Auth: Public

{ "ok": true, "service": "sdkey-api" }

Auth

POST/api/v1/auth/register

Auth: Public (rate: 20/min)

Body: email, password (12–128), name, turnstileToken (Cloudflare Turnstile). Sets session cookie. 201 { success, developer }.

POST/api/v1/auth/login

Auth: Public (rate: 20/min)

Body: email, password, turnstileToken. Sets session cookie.

POST/api/v1/auth/logout

Auth: Public

Clears session cookie.

GET/api/v1/auth/me

Auth: Cookie or Bearer

{ success, developer }

Apps

All routes require cookie or Bearer.

POST/api/v1/apps/create

Auth: Required

Body: name, optional version (default 1.0.0). Returns application + sdkHint; embed publicKeyB64 in clients.

GET/api/v1/apps/

Auth: Required

{ success, applications }

GET/api/v1/apps/:id

Auth: Required

Single application owned by the developer.

GET/api/v1/apps/:id/licenses

Auth: Required

Query: limit, cursor. Paginated license list.

POST/api/v1/apps/:id/licenses/extend

Auth: Required

Body: seconds (positive, max ~10 years). Extends active licenses for the app.

GET/api/v1/apps/:id/logs

Auth: Required

Query: limit, cursor. Security / validation logs.

Licenses (developer)

POST/api/v1/licenses/create

Auth: Required (rate: 30/min)

Default account mode — server mints plaintext keys once.

{
  "applicationId": "<uuid>",
  "amount": 1,
  "durationSeconds": 2592000,
  "note": "optional",
  "mask": "SDKY-XXXX-XXXX-XXXX-XXXX"
}

201: { success, keys, warning }. Server stores SHA-256 + prefix.

POST/api/v1/licenses/create-blind

Auth: Required (rate: 30/min)

Private mode — client mints; send hashes only (no plaintext licenseKey).

{
  "applicationId": "<uuid>",
  "keys": [
    {
      "licenseKeyHash": "<64 hex sha256>",
      "licenseKeyPrefix": "SDKY-ABCD…",
      "durationSeconds": 0,
      "noteCiphertextB64": "optional"
    }
  ],
  "mask": "optional"
}

POST/api/v1/licenses/:id/ban

Auth: Required

Ban a license; invalidates KV cache.

DELETE/api/v1/licenses/:id

Auth: Required

Delete a license.

Session & validate (client)

Public SDK endpoints — detailed guide: License control.

POST/api/v1/session/init

Auth: Public (rate: 60/min)

Body: appId, clientNonceB64 (32 bytes). Returns signed hello + session material.

POST/api/v1/licenses/validate

Auth: Public (rate: 120/min)

Sealed AES-GCM envelope required. HWID lock on first success. See License control.

Metrics

GET/api/v1/metrics/overview

Auth: Required

App counts, license status tallies, validations last 24h.

Account

POST/api/v1/account/mask

Auth: Required

Body: mask (string or null). Default license key mask.

POST/api/v1/account/mode

Auth: Required (rate: 20/min)

Body: mode (default | private), password.

POST/api/v1/account/vault

Auth: Required (rate: 20/min)

Body: vault check blob fields + password. Used for Private-mode note encryption in the browser.

POST/api/v1/account/api-keys

Auth: Required

Create key — see API keys.

GET/api/v1/account/api-keys

Auth: Required

List key metadata (no plaintext).

POST/api/v1/account/api-keys/:id/revoke

Auth: Required

Soft-revoke a key.

Rate limits

auth              20 / min
session           60 / min
validate         120 / min
licenseCreate     30 / min
blindCreate       30 / min
accountSensitive  20 / min
apiKeyAuth        30 / min  (failed Bearer attempts)