API keys
Server-to-server and automation flows should use an API key.- Header:
Authorization: Bearer <token> - Token format:
idx_prefix followed by a secret string issued when the key is created.
households:read). Requests without the required permission receive 403.
Optional restrictions on the key (such as IP allowlists and rate limits) are enforced by the API.
Web session
The Headlight web application signs users in via WorkOS. The browser holds a session cookie (wos-session). That cookie is intended for interactive use in the app, not for typical third-party integrations.
Reference vs playground
These docs are reference-first. Trying endpoints from the hosted docs playground may fail across origins until your deployment explicitly allows the docs origin. Use curl, your own HTTP client, or Postman againsthttps://app.withheadlight.com when integrating.