> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install and configure the Grantex Python SDK for delegated authorization of AI agents.

## 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](/release-status).

```bash theme={null}
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](/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](/guides/sdk-execution-authority).

* Python 3.9 or higher
* [httpx](https://www.python-httpx.org/) (sync HTTP client)
* [PyJWT](https://pyjwt.readthedocs.io/) >= 2.13 with [cryptography](https://cryptography.io/) >= 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.

<Warning>
  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](/migration-enforcement).
</Warning>

<Note>
  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.
</Note>

<Note>
  Version `0.5.0` adds EVM payment responses and authenticated principal/agent
  reservation reconciliation for [Base USDC custody](/guides/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](/guides/agent-wallet-governance).
</Note>

## Quick Start

```python theme={null}
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:

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

If neither is set, a `ValueError` is raised.

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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.

```python theme={null}
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](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.