API reference

Base URL https://api.superdrm.com (hosted) or https://api.<your domain> (on-premises). JSON in and out unless stated. Every error is {"error": "<message>", "code": "<code>"} with a 4xx/5xx status.

#Authentication

API key scopes: keys:write, keys:read, licence:serve, usage:read, admin (grants all). Only a SHA-256 of a key is stored; the first 15 characters are shown as its prefix.

#Service

#GET /

Product banner. No auth.

#GET /health

No auth. 200 when the vault and database answer, 503 otherwise.

{ "ok": true,
  "vault": { "provider": "pkcs11", "id": "pkcs11:superdrm-kek-1", "ok": true, "detail": "YubiHSM 2" },
  "db": { "ok": true, "detail": "postgres" },
  "fairplay_ksm": { "ok": true, "detail": "production credentials · Apple FPS SDK 26.0.4" },
  "widevine": { "env": "prod", "partners": ["widevine:prod"], "builtin_uat": false },
  "install": { "mode": "licensed", "org": "Acme", "tenant_cap": 10, "tenants": 3 },
  "time": "2026-09-16T12:00:00.000Z" }

#Key Protect

#POST /v1/keys — scope keys:write

Issue (or fetch, if content_id exists) one content key.

Response: content_id, kid (hex), key (hex, plaintext over TLS), iv (hex), scheme, systems, wv_pssh (base64 pssh box or null), pr_pssh, fp_hls (the URI=… attribute set for EXT-X-KEY), wv_provider, key_source (widevine | local | import), licence_urls (EME key system → URL), fairplay_cert_url, created.

#POST /v1/keys/import — scope keys:write

Bring your own key (a previous vendor's CPIX, your KMS). SuperDRM seals it and licences Widevine for it via provider-supplied keys.

200 with the same shape as /v1/keys. 409 when the id already holds a different kid. 400 on bad hex.

#GET /v1/cpix?k=<content_id>&c=<label>&EncryptionScheme=cbcs|cenc — scope keys:write

Same as POST /v1/keys, returned as CPIX 2.3 XML (application/xml). Elements: ContentKey kid explicitIV → PlainValue; one DRMSystem per system with PSSH (Widevine, PlayReady), ContentProtectionData, and HLSSignalingData playlist="media|master" (FairPlay). Header X-SuperDRM-Created: 1|0. A drop-in for the EZDRM key generator.

#GET /v1/keys?limit=100 — scope keys:read

Newest first: content_id, kid, scheme, label, systems, wv_provider, key_source, created_at, revoked_at.

#GET /v1/keys/:content_id[?reveal=1] — scope keys:read (reveal needs keys:write)

Metadata plus PSSH; reveal=1 adds the plaintext key.

#POST /v1/keys/:content_id/revoke — scope keys:write

{"revoked": true|false}. Every later licence for the id is refused with revoked.

#Licence tokens

#POST /v1/tokens — scope licence:serve

Mint a player token server-side instead of signing HS256 yourself.

Response: token, exp, servers (EME key system → licence URL with ?lt= appended), fairplay_cert_url.

#Token claims (if you sign them yourself)

HS256 JWT over the tenant's token_secret (hex → bytes):

#Policy vocabulary

Merged in order: built-in defaults → tenant settings.policy → token pol (or X-SuperDRM-Policy on relays) → auth-webhook policy.

#Attestation

Management (API key): POST/GET /v1/attest/devices, POST /v1/attest/devices/:id/revoke, POST/GET /v1/attest/images. Device-facing (open; the quote is the credential): POST /v1/<tenant>/attest/challenge → nonce, POST /v1/<tenant>/attest/verify → 15-minute attestation token. Full contract, trust model and client script: Attested devices.

#License Service

CORS is open on these routes (Access-Control-Expose-Headers: X-SuperDRM-Security). <tenant> is the tenant slug.

#POST /v1/<tenant>/license/widevine|fairplay|clearkey|playready

Body: the raw CDM challenge (Widevine bytes; FairPlay SPC raw, or spc=<base64> form, or {"spc":…} JSON; Clear Key {"kids":[…]}). Auth, one of:

• ?lt=<token> — player form.
• Authorization: Bearer sdrm_… + ?cid=<content_id> + optional X-SuperDRM-Policy: {json} — server relay form.

Response: raw licence bytes (application/octet-stream; Clear Key application/json JWK set), header X-SuperDRM-Security: L1|L3|hw|sw, Cache-Control: no-store. Every attempt writes a meter row.

#GET /v1/<tenant>/fairplay/cert

The tenant's FairPlay application certificate (application/pkix-cert). 404 until installed.

#Licence error codes

#Authorization webhook

Set auth_webhook on a tenant and SuperDRM POSTs before every token-authenticated licence:

{ "content_id": "…", "system": "widevine", "sub": "user-42", "ref": "share-9", "ip_hash": "…" }

Reply {"allow": true, "policy": {…}} or {"allow": false, "reason": "share revoked"} within 2.5 s. Allows are cached 20 s per (content, user, system). Header X-SuperDRM-Tenant carries the slug.

#Usage and self-service

#GET /v1/usage?from=YYYY-MM-DD&to=YYYY-MM-DD — scope usage:read

{ from, to, totals: { widevine: { ok, failed }, … }, keys_issued, daily: [{ day, system, ok, n }] }. Default: last 30 days.

#GET /v1/usage/licences?limit=100 — scope usage:read

Recent meter rows: id, content_id, system, kind (license|renewal|service_cert), security, device_hash, user_ref, ref, bytes_out, ms, ok, error, issued_at.

#GET /v1/me — scope usage:read

Tenant profile, enabled systems, DRM switches (public halves), API keys (prefixes), your scopes.

#POST /v1/me/rotate-token-secret — scope admin

New token_secret (hex), shown once. Old tokens stop verifying immediately.

#Portal

Everything the self-service portal does is plain JSON under /v1/portal/* with the session cookie sdsess; every write needs the X-SuperDRM-Portal: 1 header (that plus SameSite=Lax is the CSRF story). Public: signup, verify-email, login, logout, reset/request, reset/perform, invite/accept. Session: me, keys, usage, events, domains (+/verify), team (+invite/remove), plan, rotate-token-secret, sessions, accounts. See Portal & console.

#Admin (operator token)

#Example: relay from an edge function

const r = await fetch(`${SUPERDRM_URL}/v1/${SUPERDRM_TENANT}/license/${system}?cid=${contentId}`, {
  method: "POST",
  headers: { Authorization: `Bearer ${SUPERDRM_KEY}`, "Content-Type": "application/octet-stream",
             "X-SuperDRM-Policy": JSON.stringify({ hw: strict }) },
  body: challenge,
});
if (r.status === 404) return relayToPreviousVendor(system, challenge);   // no_key: packaged before the switch
if (!r.ok) throw new Error(`superdrm ${r.status}: ${await r.text()}`);
return new Uint8Array(await r.arrayBuffer());

curl -s -X POST "https://api.superdrm.com/v1/<tenant>/license/widevine?cid=<content_id>" \
  -H "Authorization: Bearer sdrm_live_…" -H 'X-SuperDRM-Policy: {"hw":true}' \
  --data-binary @challenge.bin -o licence.bin -w '%{http_code}\n'

Updated September 2026