External Integrations
Ads Platform External Documentation
Minimal integration documentation for authentication, screen-first device binding, runtime device endpoints, API keys, and operational errors.
What This Covers
This is the canonical external docs surface for the current platform implementation in apps/api. It is intentionally minimal and implementation-truthful.
Authentication and Tenant Context
Clerk JWT, device Bearer auth, role expectations.
Screen-First Device Binding
Provisioning codes, register flow, replacement behavior.
Device Runtime API
Playlist, config, telemetry endpoints for TV runtime.
Error Model and Retries
Error envelope, correlation IDs, retry guidance.
Quickstart
- 1.Create venue and screen in tenant context (/v1/venues, /v1/screens).
- 2.Generate screen-bound provisioning code with POST /v1/devices/provisioning-codes.
- 3.Enter pairing code in the TV app and register via POST /devices/register.
- 4.Persist one-time dak_ key on device and call runtime endpoints with Bearer auth.
- 5.Monitor status/errors via provisioning status checks and X-Request-ID correlation IDs.
Minimal Endpoint Surface
| Method | Path | Auth | Summary |
|---|---|---|---|
| POST | /devices/register | Public (no auth header) | Registers a TV device from a provisioning code and returns a one-time device API key. |
| GET | /devices/:id/playlist | Device API key (dak_) in Authorization header | Returns active playlist (Turso, on-demand, or R2 fallback) for the authenticated device context. |
| GET | /devices/:id/config | Device API key (dak_) in Authorization header | Returns device config or a default config payload with HTTP 200 when no custom config exists. |
| POST | /devices/:id/events | Device API key (dak_) in Authorization header | Accepts 1-100 telemetry events and returns accepted count. |
| POST | /v1/devices/provisioning-codes | Clerk JWT (tenant-scoped) | Generates a screen-bound pairing code for device onboarding. |
| GET | /v1/devices/provisioning-codes/:code/status | Clerk JWT (tenant-scoped or platform-admin scoped read) | Returns pending/activated/expired status plus screen and optional device reference. |
| POST | /v1/devices/:id/revoke | Clerk JWT (tenant-scoped) | Suspends a bound device, revokes active device keys, and resets screen to provisioning. |
| GET | /v1/api-keys | Clerk JWT (tenant-scoped) | Lists tenant machine API keys (prefix, status, usage metadata). |
| POST | /v1/api-keys | Clerk JWT + role tenant_admin|super_admin | Creates tenant API key and returns one-time key material. |
| POST | /v1/api-keys/:id/rotate | Clerk JWT + role tenant_admin|super_admin | Rotates key hash/prefix and returns new one-time key material. |
| POST | /v1/api-keys/:id/revoke | Clerk JWT + role tenant_admin|super_admin | Marks tenant API key as revoked. |
System Context
Architecture context is available in Architecture Context.