Authentication

Two ways in: the session cookie the app uses, or an API key for scripts and tools. Either one makes you the same user with the same role. A key can also be limited to reading.

API keys

Create one in Settings → API keys (see API keys) and send it as a bearer token:

curl https://api.media.binatang.nl/library/albums \
  -H "Authorization: Bearer media_pk_…"

x-api-key: media_pk_… is accepted too.

A key carries the read scope, plus write if you allowed writes when you created it. Without write, every request other than GET, HEAD or OPTIONS is refused with a 403, including a few POSTs that only look things up, such as POST /albums/refs/check.

Keys cannot manage keys or change the password. /auth/me/api-keys and POST /auth/me/password need the session cookie, whatever scopes the key has.

To check which credential a request used, call GET /auth/me. Its auth field says how the request authenticated, and never includes the key itself:

{ "username": "me", "role": "viewer", "auth": { "via": "api_key", "scopes": ["read"], "prefix": "media_pk_3qX2abc" } }

Session cookie

POST /auth/login sets a JWT in an HttpOnly cookie, and every other endpoint reads it from there. POST /auth/logout clears it.

curl -c jar.txt -X POST https://api.media.binatang.nl/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"me","password":"…"}'

curl -b jar.txt https://api.media.binatang.nl/library/albums

If a request carries both a key and a cookie, the key is used. A key that has been revoked, has expired or is wrong is a 401. The request does not fall back to the cookie.

Roles

viewer and admin. Everything under the administration surface requires admin.

401 versus 403

401	No valid session or key: signed out, or the key was revoked, has expired or is wrong.
403	Signed in, but not allowed: your role is too low, or your key is read-only. The detail says which.

Personal versus shared data

Endpoints that return your state — favourites, wishlist, notes, personal charts — resolve the user from the session or key. There is no way to ask for another user's annotations.

Anything scoped to your own listening additionally needs a scrobble link; without one those endpoints return empty rather than failing.