Librarika Hubfor developers Test environment
Menu

Authentication

DPoP

DPoP (RFC 9449) binds a token to a key pair your client holds, so a stolen token is useless without the private key. It is required for public clients (native and browser apps), for their access and refresh tokens, and recommended for confidential clients; a library may require it for a client. API keys are not DPoP-bound.

How to use it

  1. Create a key pair once per installation: ES256 (P-256) is the usual choice. Keep the private key non-exportable where the platform allows it (WebCrypto with extractable: false, the platform keystore on mobile).
  2. Authorize with dpop_jkt, the RFC 7638 thumbprint of the public key, so the code is bound to it.
  3. On every token request (code exchange and refresh), send a DPoP header: a JWT with header typ: dpop+jwt, alg: ES256 and jwk (the public key), and claims:
    • htm: the HTTP method, POST;
    • htu: the token endpoint URL, without query or fragment;
    • iat: the current time;
    • jti: a new unique value. The token answer has token_type: DPoP.
  4. On every API call, send Authorization: DPoP <access token> (not Bearer) and a new proof with the call's htm and htu and also ath: the base64url SHA-256 of the access token.
GET /lms/v1/me/holds HTTP/1.1
Host: api.librarika.dev.raynux.com
Authorization: DPoP $LIBRARIKA_ACCESS_TOKEN
DPoP: $PROOF_FOR_GET_ME_HOLDS

Rules the server checks

  • htm and htu match the request exactly.
  • iat is within 60 seconds of the server's clock: keep your clock synchronised.
  • jti is never reused: a replayed proof is refused.
  • ath matches the access token on API calls.
  • The proof's key is the key the token is bound to.

Any failure is 401 dpop_invalid, with WWW-Authenticate: DPoP. Sign a fresh proof and try again; never cache proofs.

Nonces

The protocol lets a server require a nonce (DPoP-Nonce header, answer use_dpop_nonce). Librarika does not require one yet. Code for it anyway: when an answer carries DPoP-Nonce, put that value in a nonce claim and retry once.

Environments

A key or token issued in the test environment is refused in production and the reverse. The answer is 401 invalid_token, the same as for any invalid token: the API does not reveal that the environment was wrong. Check which host you call when a token you just received is refused.