External Integrations

API Key Model

How device runtime keys and tenant machine keys differ, and how lifecycle operations work.

Key Families

device_api_keys (dak_...)

  • Issued by POST /devices/register.
  • Used only by TV runtime calls under /devices/:id/*.
  • Returned once in plaintext; stored as hash on server.
  • Revoked automatically on replacement provisioning or explicit revoke.

api_keys (ak_...)

  • Managed via /v1/api-keys endpoints.
  • For tenant machine/integration access workflows.
  • Create and rotate responses include one-time key secret.
  • Revoke marks key status as revoked and blocks use.

Permissions

POST /v1/api-keys, POST /v1/api-keys/:id/rotate, and POST /v1/api-keys/:id/revokerequire tenant_admin or super_admin. Other roles receive 403 AUTH_FORBIDDEN.

Tenant API Key Endpoints

MethodPathSummaryStatuses
GET/v1/api-keysLists tenant machine API keys (prefix, status, usage metadata).200
POST/v1/api-keysCreates tenant API key and returns one-time key material.201, 403
POST/v1/api-keys/:id/rotateRotates key hash/prefix and returns new one-time key material.200, 403, 404
POST/v1/api-keys/:id/revokeMarks tenant API key as revoked.200, 403, 404

One-Time Secret Handling

  • Capture the key value immediately when returned by create/rotate APIs.
  • Do not expect retrieval of full key value in later list calls; only prefix/metadata are returned.
  • Rotate keys on compromise or scheduled policy, then revoke old keys.
  • Treat both dak_ and ak_ values as credentials and store in secrets managers.