Authentication
Every request authenticates with a bearer token in the Authorization header.
API keys
Keys are prefixed by mode: jw_live_ for production and jw_test_ for the
sandbox. The full secret is shown once at creation — store it somewhere safe.
Never ship a secret key in client-side code or a mobile app. If a key leaks, rotate it immediately.
Scopes
Scope each key to exactly what it needs. A key that only scans for compliance
should hold just shield:scan.
A key with scopes can call only the endpoints those scopes cover — every other
route returns 403. scenes:* and models:* are live today. shield:scan,
distribution:*, and webhooks:manage are reserved — accepted on a key, but
no endpoint enforces them yet (their APIs are coming soon).
Test vs live mode
A key’s mode is fixed at creation and shown in its prefix — jw_test_ or
jw_live_. Test keys are intended to be non-billable, so you can build without
spending. Swap the key for a live one to go to production — no code change.
There’s no separate sandbox host yet: test keys hit the same API, distinguished by mode. A dedicated sandbox that returns canned fixtures is coming soon.
Site scoping
Keys are workspace-level by default. If you run a network of paysites, you can scope a key to a single site to limit blast radius — it can then only read and write that site’s scenes.
Rotating keys
Rotation issues a new secret for the key, keeping its id, mode, scopes, and site scoping. The new secret is returned once; the previous secret stops working immediately, so deploy the new one before rotating.