Scopes

A scope is a named permission carried by an access token. Each protected endpoint requires a specific scope; a request without it returns 403 insufficient_scope.

Scope reference

Most scopes act on behalf of a signed-in user and require a user-delegated token from the Authorization Code + PKCE flow of a login client.

Scope	Grants	Endpoints	Token
remilia:stats.read	Read the authenticated user's account statistics	GET /me/stats	User-delegated
remilia:notifications.read	Read the authenticated user's notifications	GET /me/notifications	User-delegated
remilia:pokes.write	Poke other users, attributed to the authenticated user	POST /users/{handle}/poke	User-delegated
remilia:beetle.read	Read the authenticated user's Beetle game state and cards	GET /me/beetle, GET /me/beetle/cards	User-delegated
remilia:chat.read	Read global chat messages	GET /global-chat/messages	User-delegated or app-only
remilia:chat.write	Post to global chat as the authenticated user	POST /global-chat/messages	User-delegated
remilia:directory.read	Resolve and enumerate public directory identities	POST /directory/resolve, GET /users	User-delegated or app-only

Two endpoints need no remilia: scope:

• GET /users/{username} — public; no token required at all.
• GET /me — any user-delegated token, even a bare openid grant.

Checking issued scopes

The token response's scope field is a space-delimited string.

{
  "scope": "openid remilia:stats.read remilia:pokes.write"
}

Errors

A valid token without the required scope returns:

{
  "error": {
    "code": "insufficient_scope",
    "message": "scope remilia:pokes.write required"
  }
}

A user-delegated endpoint called with an app-only token returns 403 requires_user. The token carries the scope but no user. Use a login client instead.