AXG Python SDK

Verify AXG Passports before executing an AI-proposed action.

A Passport is AXG's signed proof that an action was authorized for one app, one tenant, one action and one exact payload. This SDK checks all of that, plus the signature, validity window and single use. See Passport for the concepts.

Installation

pip install "axg-python-sdk @ git+https://github.com/pinheirodps/axg@v0.4.0#subdirectory=sdks/axg-python-sdk"

The PyPI package (pip install axg-python-sdk) is prepared by the release workflow; the changelog announces its first upload.

Requires Python 3.11+ (PyJWT with cryptography is installed with it).

Verify a Passport

Verify against the actionable_payload returned by AXG, and execute exactly that payload.

from axg_python_sdk import AxgVerificationError, InMemoryReplayCache, verify_passport

replay_cache = InMemoryReplayCache()  # share one store (e.g. Redis SET NX) across replicas

try:
    claims = verify_passport(
        passport,
        actionable_payload,
        app_id="support",                       # must match the Passport audience
        tenant_id="acme",                       # optional, recommended
        allowed_action_types=["issue_refund"],  # optional, recommended
        jwks_url="https://axg.example.com/.well-known/jwks.json",
        replay_cache=replay_cache,              # optional: reject a Passport used twice
    )
except AxgVerificationError as exc:
    reject(exc.code)  # never execute on failure
else:
    issue_refund(**actionable_payload)

verify_passport returns the claims (sub, aud, tenant_id, action_type, policy, azp, jti…). Pass public_key= (PEM) instead of jwks_url to verify offline.

Async services

AxgClient keeps a cached JWKS client (keys are refetched only for an unknown kid) and runs the check in a worker thread:

from axg_python_sdk import AxgClient

axg = AxgClient("https://axg.example.com")
claims = await axg.verify_passport(passport, actionable_payload, app_id="support", tenant_id="acme")

MCP tools

Inside an MCP tool, check that AXG authorized exactly this tool call. The gateway puts the Passport and the authorized payload in params._meta (io.axg/passport, io.axg/actionable_payload); every argument the tool received must match the authorized payload.

from axg_python_sdk import verify_mcp_tool_call

claims = verify_mcp_tool_call(
    meta=params_meta,
    tool_name="issue_refund",
    arguments=arguments,
    app_id="support",
    jwks_url="https://axg.example.com/.well-known/jwks.json",
)

Approvals

When AXG answers CONFIRM or SUGGEST, the response carries an approval ticket. After the right person approves, exchange it for a Passport (Human approvals):

from axg_python_sdk import AxgApprovalError, submit_approval

result = submit_approval(
    "https://axg.example.com", api_key,
    ticket=approval["ticket"], actionable_payload=payload,   # exactly what the approver saw
    approver_id="ana", approver_role="end_user",              # outcome="deny" to refuse
)
passport, to_execute = result["passport"], result["actionable_payload"]

AxgClient(base_url, api_key=...).submit_approval(...) is the async variant. Refusals raise AxgApprovalError with AXG's status_code (403 wrong approver, 409 payload or policy changed, 503 AXG unavailable).

Errors

AxgVerificationError.code is one of:

Compatibility

Verifies Passport v2 (current) and v1 (issued before AXG 0.2). The payload hash uses the same canonical JSON as AXG and the Node SDK, checked against shared test vectors.

Development

pip install -e . && pip install pytest pytest-asyncio
pytest