{% 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
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. |
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.
{
"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.
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-proof | invalid_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-token | invalid_token |
Refresh once, then retry. |
session-ended | invalid_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 %}