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

# Authentication

> How a request says who is calling.

Every request acts as one person. There is no household-wide key.

## Session cookie

The web app sends the session cookie it sets when you sign in: the
`__Secure-better-auth.session_token` cookie. A request without it, or with an expired one, gets a
`401`.

Requests that change something with the cookie must also send an `Origin` header for the app's own
origin, or they get a `403`.

## Personal API tokens

A personal token belongs to the person who created it and acts as that person, with that person's
role, in the household it was created in. The key is shown once, when you create it; keep it then,
because only a masked version (`onss_live_••••3f9a`) is shown afterwards.

Send the key in the `Authorization` header:

```http theme={null}
GET /v1/week HTTP/1.1
Authorization: Bearer onss_live_…
```

A token reads: the routes that list the `token` security scheme accept it. Changes still need the
web app's session for now. When a request carries an `Authorization` header, that header alone says
who is calling: a malformed, unknown or revoked key gets a `401` even beside a valid cookie. A
session token is not a key and is refused the same way.

Revoking a token, or leaving the household, stops everything that uses it on the next request. A
token cannot list, create or revoke tokens: those routes answer `403` with
`auth.token-not-accepted` to any request that carries an `Authorization` header.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.