Python SDK

Installation

Published release: grantex==0.7.2. The published wheel and sdist hashes match the validated CI artifacts. A clean pinned public-index installation and import passed on the workstation; see Release Status.

python -m pip install grantex==0.7.2

The unpinned python -m pip install grantex command follows PyPI’s current release. Keep the exact version above in reproducible builds. See Release Status before upgrading.

Requirements

Version 0.7.1 adds opt-in current_authority, expected_principal_id and expected_agent_did verification options. Use host-authenticated identity and an uncached trusted-issuer callback; local signature checks alone do not prove current revocation. See SDK execution authority.

Python 3.9 or higher
httpx (sync HTTP client)
PyJWT >= 2.13 with cryptography >= 48.0.1 (for offline token verification)

All dependencies are installed automatically with the SDK. Version 0.6.0 adds client.webauthn.create_enrollment_session() for principal-authenticated hosted passkey registration and client.anomalies.get_response_policy() / set_response_policy() for the account-level irregularity response mode. Both server capabilities are default-off for self-hosted deployments and require explicit operator rollout; both are enabled on the Grantex-hosted service. An SDK install alone does not enable them. Version 0.6.1 adds typed WebAuthnGrantEvidence references to grant and verification responses and the updated VC WebAuthn attestation. It does not enable hosted server flags or add custom assertion UI helper methods.

Version 0.7.0 introduces breaking enforcement defaults: audience binding, denial of capped calls without trusted amounts, and online revocation checks. Register allowed resource servers before audience-bound authorization. Signature-only verification is not current-state enforcement. Python 3.9+ remains supported. Follow the migration guide.

Version 0.5.1 is a patch release. enforce() applies the tightest budget cap and denies malformed, negative, or non-finite caps and amounts (calls that earlier versions allowed with such values are now denied); the FastAPI enforcer reads the Authorization header; grant-token verification caches the JWKS and runs off the event loop; resource ids are percent-encoded in request paths; single-use authorization codes are never retried; and event streams bound connect time.

Version 0.5.0 adds EVM payment responses and authenticated principal/agent reservation reconciliation for Base USDC custody. It retains bounded refresh lost-response recovery from 0.4.1 and the layered policy, exact approval, reload, and ES256 DPoP wallet clients from 0.4.0. It does not add an automatic x402 HTTP payment-and-retry wrapper; applications must implement their merchant HTTP flow. See Agent Wallet Governance.

Quick Start

from grantex import Grantex, AuthorizeParams

client = Grantex(api_key="gx_live_...")

# Register an agent
agent = client.agents.register(
    name="travel-assistant",
    scopes=["booking:read", "booking:write"],
    description="Books flights and hotels on behalf of users",
)

# Start the authorization flow
auth = client.authorize(AuthorizeParams(
    agent_id=agent.id,
    user_id="user_abc123",
    scopes=["booking:read", "booking:write"],
))

# Redirect the user to the consent URL
print(auth.consent_url)

client.close()

Configuration

The Grantex client accepts three keyword-only arguments:

Parameter	Type	Default	Description
`api_key`	`str`	`GRANTEX_API_KEY` env var	Your Grantex API key. Required.
`base_url`	`str`	`https://api.grantex.dev`	Override the API base URL (e.g. for self-hosted).
`timeout`	`float`	`30.0`	Request timeout in seconds.

API Key Resolution

The client resolves the API key in this order:

The api_key keyword argument passed to the constructor.
The GRANTEX_API_KEY environment variable.

If neither is set, a ValueError is raised.

import os

# Option 1: Pass directly
client = Grantex(api_key="gx_live_...")

# Option 2: Set environment variable
os.environ["GRANTEX_API_KEY"] = "gx_live_..."
client = Grantex()

# Option 3: Custom base URL for self-hosted deployments
client = Grantex(
    api_key="gx_live_...",
    base_url="https://grantex.internal.example.com",
    timeout=60.0,
)

Context Manager

The Grantex client implements the context manager protocol. Using with ensures the underlying HTTP connection pool is properly closed when you are done:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    agents = client.agents.list()
    print(f"Total agents: {len(agents.agents)}")
# Connection pool is closed automatically

This is equivalent to calling client.close() manually:

client = Grantex(api_key="gx_live_...")
try:
    agents = client.agents.list()
finally:
    client.close()

Resource Clients

The Grantex client exposes the following resource clients as attributes:

Attribute	Type	Description
`agents`	`AgentsClient`	Register, list, update, and delete agents
`grants`	`GrantsClient`	Get, list, revoke, delegate, and verify grants
`tokens`	`TokensClient`	Exchange, verify, and revoke tokens
`audit`	`AuditClient`	Log, list, and retrieve audit entries
`webhooks`	`WebhooksClient`	Create, list, and delete webhook endpoints
`billing`	`BillingClient`	Subscription status, checkout, and portal
`policies`	`PoliciesClient`	Create, list, update, and delete policies
`compliance`	`ComplianceClient`	Summaries, exports, and evidence packs
`anomalies`	`AnomaliesClient`	Detect, list, and acknowledge anomalies
`scim`	`ScimClient`	SCIM 2.0 user provisioning and tokens
`sso`	`SsoClient`	OIDC SSO configuration and login
`passports`	`PassportsClient`	Issue, list, get, and revoke MPP agent passports
`vault`	`VaultClient`	Store, list, get, delete, and exchange service credentials
`budgets`	`BudgetsClient`	Per-grant spending budgets and transactions
`events`	`EventsClient`	SSE event streaming
`usage`	`UsageClient`	Usage metering and history
`domains`	`DomainsClient`	Custom domain verification
`webauthn`	`WebAuthnClient`	FIDO2/WebAuthn passkey management
`credentials`	`CredentialsClient`	Verifiable Credentials and SD-JWT
`commerce`	`CommerceClient`	Commerce V1/OACP merchant discovery, catalog, checkout, webhooks, and ops
`dpdp`	`DpdpClient`	DPDP Act 2023 records — consent, grievances, erasure, exports

Standalone Functions

In addition to the client, the SDK exports standalone utility functions:

from grantex import (
    verify_grant_token,      # Offline JWT verification via JWKS
    generate_pkce,           # Generate PKCE code_verifier + code_challenge
    verify_webhook_signature, # Verify webhook payload signatures
)

Data Model Conventions

All response types are frozen dataclasses with snake_case field names. Lists are returned as Python tuple objects for immutability.

agent = client.agents.get("agt_abc123")

# Fields use snake_case
print(agent.developer_id)
print(agent.created_at)

# Scopes are a tuple
print(agent.scopes)  # ('booking:read', 'booking:write')

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: sanjeev@orchestrum.in or mishra.sanjeev@gmail.com.

Overview

Authorization

Resources

Enforcement

Reference

Installation

Requirements

Quick Start

Configuration

API Key Resolution

Context Manager

Resource Clients

Standalone Functions

Data Model Conventions

Ownership

​Installation

​Requirements

​Quick Start

​Configuration

​API Key Resolution

​Context Manager

​Resource Clients

​Standalone Functions

​Data Model Conventions

​Ownership

Installation

Requirements

Quick Start

Configuration

API Key Resolution

Context Manager

Resource Clients

Standalone Functions

Data Model Conventions

Ownership