Skip to content

JWT

Verify OIDC tokens issued by Auths bridge servers.

AuthsClaims dataclass 

AuthsClaims(sub: str, keri_prefix: str, capabilities: list[str], iss: str, aud: str, exp: int, iat: int, jti: str, signer_type: str | None = None, delegated_by: str | None = None, witness_quorum: dict | None = None, github_actor: str | None = None, github_repository: str | None = None)

Validated claims from an Auths OIDC token.

sub instance-attribute 

sub: str

Subject claim — the signer's DID.

keri_prefix instance-attribute 

keri_prefix: str

KERI prefix of the identity.

capabilities instance-attribute 

capabilities: list[str]

Capabilities granted by this token.

iss instance-attribute 

iss: str

Issuer claim — the OIDC bridge URL.

aud instance-attribute 

aud: str

Audience claim — the service this token is intended for.

exp instance-attribute 

exp: int

Expiration time as Unix timestamp.

iat instance-attribute 

iat: int

Issued-at time as Unix timestamp.

jti instance-attribute 

jti: str

Unique JWT ID for replay prevention.

signer_type class-attribute instance-attribute 

signer_type: str | None = None

Signer classification: "Human", "Agent", or "Workload".

delegated_by class-attribute instance-attribute 

delegated_by: str | None = None

DID of the delegating identity, if this is a delegated token.

witness_quorum class-attribute instance-attribute 

witness_quorum: dict | None = None

Witness quorum metadata, if witness-backed.

github_actor class-attribute instance-attribute 

github_actor: str | None = None

GitHub username, present for GitHub Actions OIDC tokens.

github_repository class-attribute instance-attribute 

github_repository: str | None = None

GitHub repository (owner/repo), present for GitHub Actions OIDC tokens.

has_capability 

has_capability(cap: str) -> bool

Check if token grants a specific capability.

has_any_capability 

has_any_capability(caps: list[str]) -> bool

Check if token grants any of the listed capabilities.

has_all_capabilities 

has_all_capabilities(caps: list[str]) -> bool

Check if token grants all of the listed capabilities.

AuthsJWKSClient 

AuthsJWKSClient(jwks_url: str, *, cache_ttl: int = 300)

JWKS client with automatic key caching for Auths OIDC token validation.

Parameters:

  • jwks_url (str) –

    The OIDC bridge's JWKS endpoint.

  • cache_ttl (int, default: 300 ) –

    How long to cache JWKS keys, in seconds (default: 300).

Examples:

jwks = AuthsJWKSClient("https://bridge.example.com/.well-known/jwks.json")
claims = jwks.verify_token(token, audience="my-service")

verify_token 

verify_token(token: str, *, audience: str, issuer: str | None = None, leeway: int = 60) -> AuthsClaims

Verify an Auths OIDC token and extract claims.

Parameters:

  • token (str) –

    Raw JWT bearer token string.

  • audience (str) –

    Expected audience claim.

  • issuer (str | None, default: None ) –

    Expected issuer claim (optional, verified if set).

  • leeway (int, default: 60 ) –

    Clock skew tolerance in seconds (default: 60).

Returns:

  • AuthsClaims –

    AuthsClaims with the validated token claims.

Raises:

  • VerificationError –

    If the token is expired, has wrong audience/issuer, or invalid signature.

  • NetworkError –

    If JWKS keys cannot be fetched.

Examples:

claims = jwks.verify_token(bearer_token, audience="my-service")
if claims.has_capability("read"):
    allow_access()

verify_token 

verify_token(token: str, *, jwks_url: str, audience: str, issuer: str | None = None, leeway: int = 60) -> AuthsClaims

Verify an Auths OIDC token (one-shot, no JWKS caching).

For production use, prefer AuthsJWKSClient which caches JWKS keys.

Parameters:

  • token (str) –

    Raw JWT bearer token string.

  • jwks_url (str) –

    URL to fetch JSON Web Key Set.

  • audience (str) –

    Expected audience claim.

  • issuer (str | None, default: None ) –

    Expected issuer claim (optional).

  • leeway (int, default: 60 ) –

    Clock skew tolerance in seconds (default: 60).

Returns:

  • AuthsClaims –

    AuthsClaims with the validated token claims.

Raises:

Examples:

from auths.jwt import verify_token
claims = verify_token(token, jwks_url="...", audience="my-service")