Librarika Hubfor developers Test environment
Menu

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.