Librarika Hubfor developers Test environment
Menu

Authentication

Clients and keys

A library administrator registers every credential in the library's Librarika dashboard and chooses its scopes. A credential belongs to that one library: its tokens see that library's data only. See Scopes for what each scope allows.

API keys

An API key is for server-to-server use. It belongs to the library, not to a person.

  • Send it as a bearer token: Authorization: Bearer $LIBRARIKA_API_KEY. Never put it in a URL: a key in a query string is answered 400 credential_in_url and revoked at once as leaked.
  • It is shown once, when it is created or rotated. Store it in a secret store, not in code.
  • It expires (30, 60, 90 or 365 days, or a date within a year) unless the library's plan allows a key without expiry and the key holds no personal-data scope.
  • A key that holds a personal-data scope (members:read, loans:read, holds:read, holds:create, holds:cancel) must have an IP allowlist; any key may have one. A call from another address is 403 ip_not_allowed.
  • Rotation issues a new key with the same settings; the old one keeps working for an overlap the administrator picks (1 hour to 7 days, 24 hours by default). Deploy the new key within the overlap.
  • API keys are not DPoP-bound and need no proof.

OAuth clients

Type For Grants Client authentication
confidential a server you control client credentials, authorization code private_key_jwt (ES256 or EdDSA, public keys registered as a JWKS, at most 3) or client_secret_basic
public a native app, a browser app, an agent authorization code only none; PKCE (S256) and DPoP required
  • Client ids are public: lrkc_ and a 26-character ULID. Client secrets start with lrk_cs_, are shown once and can be rotated; the old secret stays valid for at most 7 days.
  • members:create and members:update need a confidential client with private_key_jwt. members:read needs a confidential client (or an API key with an IP allowlist).
  • Redirect URIs match exactly, with no wildcards: https, or for native apps a loopback http://127.0.0.1:{port}/… or http://[::1]:{port}/…, or a private-use scheme in reverse-domain form. No fragments; at most 10 per client.
  • Browser apps register up to 5 exact web origins; the API and the token endpoint answer CORS for those origins only, without credentials mode.
  • The consent screen always says "Registered by" and the library's name, with the name, homepage and privacy-policy link the administrator entered.

Environments

Keys start with lrk_live_ in production and lrk_test_ in the test environment. Production refuses test keys and the test environment refuses production keys. A key or token sent to the wrong environment is answered 401 invalid_token, exactly like any other invalid credential: the API does not say why.

Limits

  • A library may register at most 25 public clients.
  • A library may hold at most 50 working API keys (active or suspended, not past their expiry or rotation overlap).

When a credential stops working

Answer Cause
401 invalid_token revoked, expired, unknown, or for the other environment
403 credential_suspended the administrator who granted it lost a power its scopes need; another administrator adopts it and it works again with the same secret
403 library_not_enabled the library switched the API off or its plan does not include it; credentials are kept
403 library_suspended the library's plan is suspended

The developer terms

Every operator of a client or key accepts Librarika's developer terms. The library chose you as the recipient of its data; you must protect it. The full text of the privacy duties is provided by Librarika and will be published here before the API opens to production libraries. In short, as the terms require at a minimum:

  • keep the data you receive secure;
  • do not sell or pass it on;
  • delete it when the library or the member revokes your access.

Members can see and revoke the apps they connected at any time, and libraries see every client and what it did.