DPoP and Nonces#

The HAAPI access token is a DPoP-bound token rather than a traditional bearer token. Every request that uses the access token must also carry a fresh DPoP proof — a short-lived JWT signed with a private key held on the device. the Curity Identity Server verifies the proof’s signature, the proof’s covered HTTP method and URL, and the proof’s freshness before honoring the request.

How It Works#

The client generates an asymmetric key pair once per HAAPI session. For each outgoing request:

1. The client constructs a DPoP JWT containing the HTTP method, target URL, issuance timestamp, and a unique jti. It signs the JWT with the private key.
2. The client sends the proof in the DPoP header alongside the access token in Authorization: DPoP <token>.
3. The server validates the proof’s signature against the public key bound to the access token, then checks that the method and URL match the request being made.

Server-Issued Nonces#

To mitigate clock skew and protect against replay across boundaries, the Curity Identity Server can require a server-issued nonce inside every DPoP proof. The server emits the nonce in a DPoP-Nonce response header; the client must include it in the next proof. When the nonce becomes stale, the server returns a 401 with error="use_dpop_nonce" and a fresh nonce, and the client retries with the updated value.

Nonce-based DPoP is enabled when the HAAPI client’s use-legacy-dpop setting is false (the default for new clients). When true, the server uses the older nonce-less DPoP behavior, kept for backward compatibility with older SDK versions that pre-date auto-managed nonces.

Nonce Management Is Automatic#

The Curity HAAPI iOS and Android SDKs manage the DPoP nonce lifecycle internally. The framework’s URL session tracks the latest DPoP-Nonce header from each response and applies it to subsequent requests. Application code that previously had to extract and re-pass the nonce can be simplified — see the upgrade guide for migration details.