---
title: jwt
sidebarTitle: jwt
---

# `keycardai.oauth.utils.jwt`


JWT Profile for OAuth 2.0 implementations (RFC 7523, RFC 9068).

This module implements JWT-related OAuth 2.0 profiles for secure token handling,
including JWT client assertions and JWT access token profiles.

RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication
and Authorization Grants
https://datatracker.ietf.org/doc/html/rfc7523

RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
https://datatracker.ietf.org/doc/html/rfc9068

Key Features:
- JWT client authentication (RFC 7523)
- JWT authorization grants (RFC 7523)
- JWT access token format (RFC 9068)
- Claims validation and verification
- Signature verification and key management

JWT Client Authentication Use Cases:
- High-security environments requiring cryptographic authentication
- Distributed systems with pre-shared keys or certificates
- Service-to-service authentication
- Environments where client secrets are not practical

JWT Access Token Benefits:
- Self-contained tokens with embedded claims
- Cryptographic integrity protection
- Reduced database lookups for token validation
- Standardized claim format across services


## Functions

### `get_claims` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_claims(jwt_token: str) -> dict[str, Any]
```


Extract all claims from a JWT token payload without verification.

This utility extracts all claims from a JWT token's payload without
performing signature verification. Useful for operational purposes
like extracting specific claims for token exchange requests.

**Args:**
- `jwt_token`: JWT token string (without Bearer prefix)

**Returns:**
- Dictionary of all claims in the JWT payload

**Raises:**
- `ValueError`: If token is malformed or cannot be decoded


## Classes

### `JWTClientAssertion` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L93" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


JWT Client Assertion utilities for RFC 7523.

Implements JWT-based client authentication as an alternative to
client secrets for OAuth 2.0 token requests.

Reference: https://datatracker.ietf.org/doc/html/rfc7523#section-3


**Methods:**

#### `create_assertion` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_assertion(client_id: str, audience: str, issuer: str, subject: str | None = None, expiration_seconds: int = 300, additional_claims: dict[str, Any] | None = None, private_key: str | None = None, algorithm: str = 'RS256') -> str
```

Create a JWT client assertion for authentication.

**Args:**
- `client_id`: OAuth 2.0 client identifier
- `audience`: Token endpoint URL (aud claim)
- `issuer`: JWT issuer (iss claim)
- `subject`: JWT subject (sub claim), defaults to client_id
- `expiration_seconds`: Token lifetime in seconds
- `additional_claims`: Extra claims to include in JWT
- `private_key`: Private key for signing (PEM format)
- `algorithm`: Signing algorithm (RS256, ES256, etc.)

**Returns:**
- Signed JWT assertion string

Reference: https://datatracker.ietf.org/doc/html/rfc7523#section-3


#### `verify_assertion` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L137" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
verify_assertion(assertion: str, expected_audience: str, public_key: str | None = None, clock_skew_seconds: int = 30) -> dict[str, Any]
```

Verify a JWT client assertion.

**Args:**
- `assertion`: JWT assertion to verify
- `expected_audience`: Expected audience claim value
- `public_key`: Public key for verification (PEM format)
- `clock_skew_seconds`: Allowable clock skew for time-based claims

**Returns:**
- Verified JWT payload claims

**Raises:**
- `OAuthInvalidTokenError`: If JWT is invalid or verification fails


### `JWTAccessToken` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


JWT Access Token profile implementing RFC 9068.

Defines the standard claims and structure for JWT-formatted access tokens
as specified in RFC 9068.

Reference: https://datatracker.ietf.org/doc/html/rfc9068#section-2


### `JWTAccessTokenHandler` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Handler for JWT Access Tokens implementing RFC 9068.

Provides utilities for creating, parsing, and validating JWT access tokens
according to the standardized profile defined in RFC 9068.

Reference: https://datatracker.ietf.org/doc/html/rfc9068


**Methods:**

#### `create_access_token` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_access_token(self, subject: str, client_id: str, audience: str | list[str], scope: str | None = None, expires_in: int = 3600, additional_claims: dict[str, Any] | None = None) -> str
```

Create a JWT access token.

**Args:**
- `subject`: Token subject (typically user ID)
- `client_id`: OAuth 2.0 client identifier
- `audience`: Token audience (resource server URLs)
- `scope`: Space-separated OAuth 2.0 scopes
- `expires_in`: Token lifetime in seconds
- `additional_claims`: Extra claims to include

**Returns:**
- Signed JWT access token string

Reference: https://datatracker.ietf.org/doc/html/rfc9068#section-2


#### `parse_access_token` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
parse_access_token(self, jwt_token: str, verify_signature: bool = True, public_key: str | None = None) -> JWTAccessToken
```

Parse and validate a JWT access token.

**Args:**
- `jwt_token`: JWT access token string
- `verify_signature`: Whether to verify JWT signature
- `public_key`: Public key for verification (PEM format)

**Returns:**
- Parsed JWT access token claims

**Raises:**
- `OAuthInvalidTokenError`: If JWT is malformed or verification fails

Reference: https://datatracker.ietf.org/doc/html/rfc9068#section-3


### `JWTAccessTokenValidator` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


JWT Access Token validation per RFC 9068.

Validates JWT access tokens according to the structured format
and security requirements defined in RFC 9068.

Reference: https://datatracker.ietf.org/doc/html/rfc9068


**Methods:**

#### `validate_token` <sup><a href="https://github.com/keycardai/python-sdk/blob/main/src/keycardai/oauth/utils/jwt.py#L303" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_token(self, jwt_token: str, required_scope: str | None = None, clock_skew_seconds: int = 30) -> dict[str, Any]
```

Validate a JWT access token.

Performs comprehensive validation including:
- Signature verification
- Expiration check
- Issuer/audience validation
- Scope validation (if required)
- Token structure compliance with RFC 9068

**Args:**
- `jwt_token`: JWT access token to validate
- `required_scope`: Required OAuth 2.0 scope (optional)
- `clock_skew_seconds`: Allowable clock skew for exp/iat claims

**Returns:**
- Validated token claims

**Raises:**
- `OAuthInvalidTokenError`: If token is invalid or expired
- `OAuthInvalidScopeError`: If required scope is not present

Reference: https://datatracker.ietf.org/doc/html/rfc9068#section-3

