Authentication
Tokens
Tokens come from the authorization server https://auth.librarika.dev.raynux.com. They are opaque strings, not JWTs: do not parse them. Access tokens start with lrk_at_ and refresh tokens with lrk_rt_, so secret scanners recognise a leaked one. Every token is issued for the resource https://api.librarika.dev.raynux.com/lms/v1 and for one library.
Getting a token
- Client credentials (a confidential client acting for the library):
POST /oauth2/tokenwithgrant_type=client_credentials, thescopeyou need and client authentication. There is no refresh token: ask for a new access token when it expires. - Authorization code with PKCE (an app acting for a member): send the member to
GET /oauth2/authorizewithresponse_type=code,client_id,redirect_uri,scope,state(required) and acode_challengewithcode_challenge_method=S256; public clients also senddpop_jkt. The member signs in to their library and consents. You receivecode,stateandissat the redirect URI; checkstateandiss, then exchange the code atPOST /oauth2/tokenwithcode_verifier(and a DPoP proof for a public client). Pushed authorization requests (POST /oauth2/par) are supported.
Lifetimes
| Token | Default lifetime |
|---|---|
| Authorization code | 60 seconds, single use |
| Access token | 15 minutes |
| Refresh token | 30 days unused; at most 90 days from the member's last sign-in |
| Remembered consent (grant) | 12 months |
These are defaults. Librarika may configure other values within fixed bounds; the configuration is read once when the service starts, so a change applies from the next start. Do not hard-code a lifetime: use expires_in from the token answer.
Refreshing
A refresh (grant_type=refresh_token) rotates: every use returns a new refresh token and the old one stops working at once. There is no grace window. Using an old refresh token again is treated as theft: the whole family of tokens is revoked, the event is recorded for the library, and the member has to sign in again.
So never refresh in parallel. If two threads, tabs or processes refresh with the same refresh token, the second is a reuse and ends the session. Serialise refreshes (one in flight at a time, the others waiting for its result) and store the new refresh token before you use the new access token.
A refresh gives the scopes that both the client's registration and the member's grant still allow, and the answer lists them. If none are left, the refresh is invalid_grant.
Member sign-in and write scopes
- Write scopes need a recent sign-in. A code that carries a write scope (
member.holds:write) is issued only if the member signed in within the last 15 minutes. This is checked at every code issuance, also when a remembered consent skips the consent screen. Sendprompt=loginto have the member sign in again. - Write scopes need a sign-in Librarika verified. A member who signs in to their library only through single sign-on (SAML or Google) gets read scopes only for now.
- Staff "log in as" sessions are refused at authorize.
When tokens end
| Event | Effect |
|---|---|
| The member revokes the app in "Connected apps" | the grant and its tokens end at once |
| The member changes their password, signs out everywhere, or changes MFA | their tokens end; the grant is kept, so they sign in again without a new consent |
| The library blocks the member (inactive, or sign-in not allowed), or removes them | at the app's next refresh the grant is revoked and the refresh answers invalid_grant; meanwhile calls are 403 member_access_required |
| The library disables or deletes the client | every token of the client stops at once |
| The library switches the API off | tokens answer 403 library_not_enabled; new tokens are refused |
A member whose library blocked them and later unblocked them must consent again in each app: nothing comes back on its own. If your app loses its refresh token this way, send the member through authorization again.
Revoking
Revoke a token you no longer need with POST /oauth2/revoke (RFC 7009) with client authentication (client_id for a public client). Revocation is bound to the client: it ends only tokens issued to the client that authenticated. Revoking a refresh token ends its whole family. Revoke on sign-out.
A revocation sent without client authentication is treated as a leak report: it ends that token and is recorded as a leak. Use it if you find one of your tokens exposed.
Errors
The token and revoke endpoints answer OAuth errors (invalid_client, invalid_grant, invalid_scope, …, RFC 6749 §5.2), not problems, because OAuth libraries expect that shape. The API answers an expired access token with 401 token_expired and any other unusable one with 401 invalid_token.