> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withheadlight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How Headlight authenticates API and web requests

## 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.

Keys can carry permission slugs (for example `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 against `https://app.withheadlight.com` when integrating.