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

Running the examples

Most Python examples in these docs are fragments that use await directly, because the SDK is async. Python only allows await inside an async function, so a fragment saved to a file and run with python fails with SyntaxError: 'await' outside function. To run one, either:

• wrap it in an async def main() and call asyncio.run(main()), as the Quickstart snippets do; or
• paste it into the asyncio REPL, which accepts top-level await: python -m asyncio.

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 the agent’s own key (from agents.create; issued today with the legacy alter_key_… prefix). 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.