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
- 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). - Authorize with
dpop_jkt, the RFC 7638 thumbprint of the public key, so the code is bound to it. - On every token request (code exchange and refresh), send a
DPoPheader: a JWT with headertyp: dpop+jwt,alg: ES256andjwk(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 hastoken_type: DPoP.
- On every API call, send
Authorization: DPoP <access token>(notBearer) and a new proof with the call'shtmandhtuand alsoath: 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
htmandhtumatch the request exactly.iatis within 60 seconds of the server's clock: keep your clock synchronised.jtiis never reused: a replayed proof is refused.athmatches 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.