Python SDK

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

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 are async. Always close them (await app.close()) or use as an async context manager.

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(), boto3_client(), scopes.list() — every credential-injection path.

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

• Every method is async. Use await and run inside an event loop.
• Models are frozen Pydantic objects. Fields are snake_case (matches the wire format).
• Methods that retrieve tokens never return the token plaintext. The SDK injects it into the outbound request.
• Public exceptions inherit from AlterSDKError. See Errors.