Python SDK

The Python SDK ships as the alter-sdk package on PyPI. Python 3.11+.

pip install alter-sdk

from alter_sdk import App, Agent, HttpMethod, Provider

Two clients

The SDK exposes two top-level clients. They share the request surface but differ in principal and identity scoping.

App

Construct with an alter_rk_… key. Acts as the application — provisions agents, mints Connect sessions, manages grants, and proxies provider calls under stored grants.

Agent

Construct with an alter_ak_… key. Workload-scoped: can only reach credentials delegated or directly bound to the agent. The right entry point for AI agents and tool-calling workloads.

Both classes expose async network and lifecycle methods. Always close them (await app.close()) or use them as async context managers.

async with App(api_key="alter_rk_…") as app:
    page = await app.list_grants()

Reference

Client

App and Agent constructors, lifecycle, with_constraints, get_agent, is_valid_key.

Calling APIs

request(), proxy_request(), scopes.list(), and spans.emit().

Provider discovery

provider_specs.* metadata, operation search, and request/response schemas.

Connect & Grants

Connect sessions, grant CRUD, delegation revoke, managed-secret grants, HITL approvals.

Agents & Keys

app.agents.* CRUD, Agent.me / trace / with_constraints, keys.derive / rotate / revoke.

Types

Pydantic models returned across the SDK surface.

Errors

Typed exception hierarchy.

FastAPI

AlterFastAPI dependency for automatic JWT capture.

LangChain

@alter_tool decorator and AlterMCPInterceptor.

MCP

AlterMCP, AlterAuthProvider, AlterContext for FastMCP servers.

Configuration

The constructor accepts an api_key argument; application code is responsible for sourcing it. The convention is to read it from the process environment:

Variable	Used by	Description
ALTER_API_KEY	application code (typical app workload)	Conventional name when the application owns one app-level key.
AGENT_API_KEY	application code (agent workload)	Conventional name when the workload runs as a managed agent.

For agent workloads, the convention is to read AGENT_API_KEY in application code:

import os
from alter_sdk import Agent

agent = Agent(api_key=os.environ["AGENT_API_KEY"])

Conventions

• Network and lifecycle methods are async. Constructors, properties, with_constraints(), get_agent(), trace(), and is_valid_key() are synchronous.
• Response and input models are Pydantic objects with snake_case fields matching the wire format. Most are frozen; APICallAuditLog, UserSpan, and EmitSpansResult are mutable.
• Methods that retrieve tokens never return the token plaintext. The SDK injects it into the outbound request.
• Public exceptions inherit from AlterSDKError. See Errors.