Authentication
Scopes
A scope is a permission of the form <resource>:<action>. A library administrator chooses the scopes of each API key and OAuth client; a member chooses, on the consent screen, which of an app's member.* scopes to grant. A token never carries a scope its credential was not given. Scope strings are part of the v1 contract: they never change meaning, and new ones are added only alongside.
There are two families, and one credential never mixes them:
- Library scopes, for API keys and client-credentials clients (and the library reads a member token may also carry).
- Member scopes (
member.*), for member tokens only: the member's own data.
Library scopes
| Scope | Allows | Personal data | Credential |
|---|---|---|---|
library:read |
GET /library |
no | any |
branches:read |
GET /library/branches, GET /library/branches/{id} |
no | any |
catalog:read |
GET /catalog/titles, GET /catalog/titles/{id} |
no | any |
availability:read |
the availability reads, and copy status on GET /catalog/titles/{id} |
no | any |
members:read |
GET /members, GET /members/{id} |
yes | confidential OAuth client, or API key with an IP allowlist |
members:create |
POST /members |
yes | confidential OAuth client with private_key_jwt |
members:update |
PATCH /members/{id}, POST /members/{id}/activate, POST /members/{id}/deactivate; implies members:read |
yes | confidential OAuth client with private_key_jwt |
loans:read |
GET /loans, GET /loans/{id}: current loans and loans returned in the last 30 days |
yes | confidential OAuth client, or API key with an IP allowlist |
holds:read |
GET /holds, GET /holds/{id} |
yes | as loans:read |
holds:create |
POST /holds |
yes | as loans:read |
holds:cancel |
POST /holds/{id}/cancel; implies holds:read |
yes | as loans:read |
Member scopes
| Scope | Allows |
|---|---|
member.profile:read |
GET /me: the member's name, number and status |
member.loans:read |
GET /me/loans, GET /me/loans/{id}: the member's current loans |
member.holds:read |
GET /me/holds, GET /me/holds/{id} |
member.holds:write |
POST /me/holds, POST /me/holds/{id}/cancel; implies member.holds:read |
Member tokens carry no email, phone or address, and v1 exposes no loan history.
Write scopes on a member token have two extra conditions: the member must have signed in within the last 15 minutes when the code is issued, and with a sign-in Librarika verified itself. See Tokens.
Actions and scopes
A verb action needs the family's write scope where there is one (member.holds:write covers cancel), or the resource's update scope when it changes the resource's own state (members:update covers activate and deactivate); otherwise it has its own scope <resource>:<verb> (holds:cancel). v1 has no delete scope.
Asking for less
Ask for the fewest scopes your integration needs. A call without a needed scope is 403 insufficient_scope, whose WWW-Authenticate header names the scope. A library credential calling a /me operation, or a member token calling a staff operation, is 403 wrong_flow.