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 answered400 credential_in_urland 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 is403 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 withlrk_cs_, are shown once and can be rotated; the old secret stays valid for at most 7 days. members:createandmembers:updateneed a confidential client withprivate_key_jwt.members:readneeds a confidential client (or an API key with an IP allowlist).- Redirect URIs match exactly, with no wildcards:
https, or for native apps a loopbackhttp://127.0.0.1:{port}/…orhttp://[::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.