{% extends "_layout.html" %} {% set title = "Invalid DPoP proof" %} {% set status = "401 Unauthorized" %} {% set description = "The DPoP header on this request was missing, malformed, replayed, or signed by the wrong key." %} {% block main %}

The DPoP header on this request was missing, malformed, already seen, or signed by a key that is not the one your token is bound to.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: DPoP error="invalid_dpop_proof"
Content-Type: application/problem+json

What to do

Fail and surface it. Do not refresh, and do not retry — retrying reproduces it, and a retry loop here reads from the server as a brute-force attempt against the key binding. The one exception is a proof refused for its time: correct later proofs by the offset between this machine’s clock and the response’s Date, retry once, and tell the user their clock is off.

A missing or stale nonce is never this: it is dpop-nonce-required, retried once with the nonce.

This is nearly always a client bug — or a clock: a proof carries the time it was made, and one more than a minute from the server’s own is refused every time. Compare this machine’s clock with the response’s Date header first; the reference client says so when they are that far apart. Then work through the proof in this order.

Check
Is there a proof at all? Every authenticated request needs one. A DPoP-bound token sent with only an Authorization header fails here.
htm and htu Must match this request’s method and URI. htu excludes the query string and fragment.
iat Within ±60 seconds. A host with a drifting clock fails every request.
jti Unique per proof. Reusing one is a replay and is refused even if everything else is correct.
The signing key Its thumbprint must equal the cnf.jkt claim in your access token. A client that regenerated its key pair but kept the old token lands here.
The nonce If the server asked for one, use it — but that is a different error, below.

Also at the token endpoint

At POST /v1/auth/token and POST /v1/auth/device the same condition is answered in the OAuth shape, invalid_dpop_proof, not with this type. A refresh refused invalid_dpop_proof ends no session: a refresh token presented without its key revokes nothing. On grant_type=refresh_token the refresh carries its own proof, and its thumbprint must match the one the token family was bound to at login.

That is deliberate and worth understanding: without it, every ordinary request would be key-bound except the one that mints the next credential — which is the only one worth stealing.

The body

{
  "type":     "https://sc.example.com/server-errors/invalid-dpop-proof",
  "title":    "Invalid DPoP proof",
  "status":   401,
  "detail":   "The proof's htu does not match the request URI.",
  "instance": "/v1/jobs",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

No required extension members. detail will usually name which check failed — useful while debugging, and not something to branch on.

{% include "_help.html" %}

What this is not

Four 401 conditions share this status and want opposite reactions. The status alone is not enough — branch on the WWW-Authenticate error= parameter and, for invalid_token, on the body’s type.

error=Do
invalid-dpop-proofinvalid_dpop_proof Fail — you are here.
(no type)use_dpop_nonce Retry immediately with the DPoP-Nonce just supplied. Cache it per origin — the authorization server and resource server have separate nonce spaces.
invalid-tokeninvalid_token Refresh once, then retry.
session-endedinvalid_token Re-authenticate, never refresh. Same header value — only the body’s type tells them apart.

A client that reads only the header is correct on three of these and loops forever on the fourth.

{% endblock %}