DPoP (Demonstrating Proof of Possession)

OAuth 2.0 DPoP (RFC 9449) for binding tokens to a client's private key.

Key Management

DPoPKey(algorithm='ES256')

Manages a DPoP asymmetric key pair.

Generate via :func:generate_dpop_key. The key pair is immutable and thread-safe after construction.

Parameters:

Name	Type	Description	Default
algorithm	str	The signing algorithm ("ES256", "RS256", etc.).	'ES256'

algorithm property

The signing algorithm.

private_key_pem property

PEM-encoded private key bytes.

public_jwk property

Public key as a JWK dict suitable for the DPoP proof jwk header.

jwk_thumbprint property

JWK Thumbprint (RFC 7638) for use as dpop_jkt parameter.

generate_dpop_key(algorithm='ES256')

Generate a new DPoP key pair.

Parameters:

Name	Type	Description	Default
algorithm	str	Signing algorithm — "ES256" (default, recommended), "ES384", "ES512", or "RS256".	'ES256'

Returns:

Name	Type	Description
A	DPoPKey	class:DPoPKey with a fresh key pair.

Proof Creation

create_dpop_proof(key, method, uri, access_token=None, nonce=None)

Create a signed DPoP proof JWT (RFC 9449).

Parameters:

Name	Type	Description	Default
key	DPoPKey	The :class:DPoPKey to sign the proof with.	required
method	str	HTTP method (e.g. "POST", "GET").	required
uri	str	The full HTTP URI of the request.	required
access_token	str | None	If provided, includes the ath claim (required for resource server requests with bound tokens).	None
nonce	str | None	Server-provided DPoP nonce (from a previous DPoP-Nonce response header).	None

Returns:

Type	Description
str	The signed DPoP proof JWT string.

Raises:

Type	Description
ValueError	If method or uri is empty, or uri is not absolute.

compute_ath(access_token)

Compute the access token hash (ath) claim value.

Used when sending a DPoP proof alongside a bound access token to a resource server.

Parameters:

Name	Type	Description	Default
access_token	str	The access token string.	required

Returns:

Type	Description
str	Base64url-encoded SHA-256 hash of the access token.

Raises:

Type	Description
ValueError	If access_token is empty.

HTTP Headers

build_dpop_headers(proof, access_token=None)

Build HTTP headers dict with DPoP proof and optional Authorization.

For token endpoint requests, only the DPoP header is needed. For resource server requests, both DPoP and Authorization: DPoP <token> headers are included.

Parameters:

Name	Type	Description	Default
proof	str	The signed DPoP proof JWT.	required
access_token	str | None	If provided, adds Authorization: DPoP <token> header.	None

Returns:

Type	Description
dict[str, str]	Dict of HTTP headers to include in the request.

Raises:

Type	Description
ValueError	If proof is empty.