Librarika Hubfor developers Test environment
Menu

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/token with grant_type=client_credentials, the scope you 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/authorize with response_type=code, client_id, redirect_uri, scope, state (required) and a code_challenge with code_challenge_method=S256; public clients also send dpop_jkt. The member signs in to their library and consents. You receive code, state and iss at the redirect URI; check state and iss, then exchange the code at POST /oauth2/token with code_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. Send prompt=login to 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.