Overview

A key resolves to the account that made it, and every request runs as that account. The rules that decide what the site may do decide what the key may do, because they are the same rules: they live in the database, not in the handlers.

The whole design fits in one sentence. A key can never do something its owner could not.

Make a key

Every key belongs to an app. In the developer portal, create an app, tick what it needs under Permissions and, under Keys, create the key. The token is shown once and stored only as a hash, so if you lose it you make another instead of recovering it.

Prefer an expiry to never. A key that expires is a key that stops mattering when you forget about it.

Your first request

curl https://uloggd.com/api/v1/me \
  -H "Authorization: Bearer ulg_live_..."

/api/v1/me needs no scope, so it answers for any live key and tells you what that key holds:

{
  "key": { "id": "...", "scopes": ["catalog.read", "library.read"] },
  "owner": { "id": "...", "username": "ada", "display_name": "Ada" }
}

Reading other people

Your key reads any profile by username, not only your own. Everything under /api/v1/profiles/{username}/… takes somebody else's name: profile, summary, library, stats, reviews, lists, screenshots, journeys and the year.

curl "https://uloggd.com/api/v1/profiles/ada/library?playing=true&games=1" \
  -H "Authorization: Bearer ulg_live_..."

The answer is what that person shows you, the key's owner: everything for a public library, nothing for a private one, and a followers-only one only if you follow them. Nobody has to create a key to be looked up, and a bot that shows whoever asked their library only needs that person's username.

The shape of an answer

A collection answers { data, page }. A single resource answers { data }. Every failure answers { error }, the 500 included. Nothing else.

Additive changes ship into v1; anything that removes a field or changes what it means waits for v2 (see Versioning).

Arcade

To put a web game you host in front of uloggd's players, read the Arcade guides. Arcade's developer and player routes are session only, so no key reaches them in this phase; its directory, store pages and identity keys are public.