Offline Verification

Overview

The verify_grant_token() function verifies a Grantex grant token’s signature and claims locally after retrieving the published JSON Web Key Set (JWKS). It avoids the online verification/revocation endpoint, but the current standalone helper fetches the remote JWKS on every invocation and is not network-free. This is ideal for service-side verification where latency matters and you want to avoid an API round-trip for every request.

Hosted tokens use the canonical issuer https://grantex.dev, even though the stable JWKS URL is served from https://api.grantex.dev. The SDK handles this alias automatically. For self-hosted deployments, it derives the expected issuer from the JWKS URL unless you set issuer or issuer_did explicitly.

Usage

from grantex import verify_grant_token, VerifyGrantTokenOptions

grant = verify_grant_token(
    "eyJhbGciOiJSUzI1NiIs...",
    VerifyGrantTokenOptions(
        jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
    ),
)

print(f"Principal: {grant.principal_id}")
print(f"Agent DID: {grant.agent_did}")
print(f"Scopes: {grant.scopes}")
print(f"Grant ID: {grant.grant_id}")

Import

from grantex import verify_grant_token, VerifyGrantTokenOptions, GrantexTokenError

Options

VerifyGrantTokenOptions configures how the token is verified:

Field	Type	Required	Default	Description
`jwks_uri`	`str`	Yes	—	URL of the JWKS endpoint (e.g. `https://api.grantex.dev/.well-known/jwks.json`).
`required_scopes`	`list[str] \| None`	No	`None`	If set, verification fails if the token is missing any of these scopes.
`clock_tolerance`	`int`	No	`0`	Seconds of leeway for `exp` and `iat` clock skew.
`audience`	`str \| None`	No	`None`	Expected `aud` claim. If `None`, audience is not validated.
`issuer`	`str \| None`	No	`None`	Expected `iss` claim. The hosted alias expects `https://grantex.dev`; custom JWKS URLs derive it when omitted.
`issuer_did`	`str \| None`	No	`None`	A `did:web` issuer used to derive the JWKS URL and expected issuer. An explicit `issuer` takes precedence.

Response

verify_grant_token() returns a VerifiedGrant frozen dataclass:

Field	Type	Description
`token_id`	`str`	The JWT `jti` claim (unique token identifier).
`grant_id`	`str`	The grant identifier (`grnt` claim, falls back to `jti`).
`principal_id`	`str`	The user/principal who authorized the grant (`sub`).
`agent_did`	`str`	The agent’s DID (`agt` claim).
`developer_id`	`str`	The developer who owns the agent (`dev` claim).
`scopes`	`tuple[str, ...]`	The granted permission scopes.
`issued_at`	`int`	Unix timestamp when the token was issued.
`expires_at`	`int`	Unix timestamp when the token expires.
`parent_agent_did`	`str \| None`	Parent agent DID (delegation chains only).
`parent_grant_id`	`str \| None`	Parent grant ID (delegation chains only).
`delegation_depth`	`int \| None`	Delegation depth (0 = root grant).

Algorithm

The algorithm is fixed to RS256 per SPEC section 11. Tokens signed with any other algorithm are rejected. This cannot be overridden.

Examples

Basic Verification

from grantex import verify_grant_token, VerifyGrantTokenOptions

grant = verify_grant_token(
    token,
    VerifyGrantTokenOptions(
        jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
    ),
)

print(f"Token ID: {grant.token_id}")
print(f"Grant ID: {grant.grant_id}")
print(f"Authorized by: {grant.principal_id}")
print(f"Agent: {grant.agent_did}")
print(f"Scopes: {grant.scopes}")

Require Specific Scopes

from grantex import verify_grant_token, VerifyGrantTokenOptions, GrantexTokenError

try:
    grant = verify_grant_token(
        token,
        VerifyGrantTokenOptions(
            jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
            required_scopes=["files:read", "files:write"],
        ),
    )
except GrantexTokenError as e:
    print(f"Verification failed: {e}")
    # e.g. "Grant token is missing required scopes: files:write"

With Audience and Clock Tolerance

from grantex import verify_grant_token, VerifyGrantTokenOptions

grant = verify_grant_token(
    token,
    VerifyGrantTokenOptions(
        jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
        audience="https://api.myservice.com",
        clock_tolerance=30,  # allow 30 seconds of clock skew
    ),
)

Verifying Delegated Tokens

Delegated tokens include additional claims for the delegation chain:

from grantex import verify_grant_token, VerifyGrantTokenOptions

grant = verify_grant_token(
    delegated_token,
    VerifyGrantTokenOptions(
        jwks_uri="https://api.grantex.dev/.well-known/jwks.json",
    ),
)

if grant.delegation_depth is not None:
    print(f"This is a delegated token (depth: {grant.delegation_depth})")
    print(f"Parent agent: {grant.parent_agent_did}")
    print(f"Parent grant: {grant.parent_grant_id}")
else:
    print("This is a root grant token")

Error Handling

verify_grant_token() raises GrantexTokenError in the following cases:

The token header uses an algorithm other than RS256
The JWKS endpoint is unreachable or returns invalid data
No matching RSA key is found in the JWKS
The token signature is invalid
The token is expired
The token issuer does not match the expected issuer
The token audience does not match audience, when configured
Required claims (jti, sub, agt, dev, scp, iat, exp) are missing
Required scopes are not present in the token

from grantex import verify_grant_token, VerifyGrantTokenOptions, GrantexTokenError

try:
    grant = verify_grant_token(token, options)
except GrantexTokenError as e:
    print(f"Token verification failed: {e}")

​Overview

​Usage

​Import

​Options

​Response

​Algorithm

​Examples

​Basic Verification

​Require Specific Scopes

​With Audience and Clock Tolerance

​Verifying Delegated Tokens

​Error Handling

Overview

Usage

Import

Options

Response

Algorithm

Examples

Basic Verification

Require Specific Scopes

With Audience and Clock Tolerance

Verifying Delegated Tokens

Error Handling