alter-sdk 0.20.0

Alter Vault Python SDK - OAuth token management with policy enforcement

Alter SDK for Python

Official Python SDK for Alter Vault — credential and authorization layer for apps and AI agents that call third-party APIs.

Tokens stay in the vault. The SDK injects the credential, refreshes it, and writes the audit row — application code only calls vault.request() (or vault.proxy_request() when the backend should make the outgoing call instead of the SDK).

Install

pip install alter-sdk

Requires Python 3.11+.

Quick example

Make an authenticated API call — no token ever touches application code.

import asyncio
from alter_sdk import App, HttpMethod

async def main():
    async with App(api_key="<api-key>") as vault:
        response = await vault.request(
            HttpMethod.POST,
            "https://api.example.com/resource",
            grant_id="<grant-id>",
            json={"example": "payload"},
        )
        print(response.status_code, response.json())

asyncio.run(main())

For a full walkthrough — sign-up, key minting, OAuth — see the Quickstart.

Two runtime modes

The SDK exposes two ways to reach a third-party API:

• vault.request(...) — retrieve mode. The SDK fetches the token from the backend and makes the outgoing call itself. Returns the third-party response.
• vault.proxy_request(...) — proxy mode. The backend holds the token, makes the outgoing call, and returns the result. Application code and the SDK never observe the token. Required for any grant configured with human-in-the-loop approval; available for any other grant when wire-level audit, strong token isolation, or backend-side policy enforcement matter.

See runtime modes for the tradeoffs and when to pick each.

Recovering from missing-grant errors

When a request fails because the user hasn't authorized the provider yet, the SDK exposes recovery context on the typed error so you can drive a re-consent flow without re-deriving anything from the call site:

from alter_sdk import NoDelegatedGrantError

try:
    await vault.request(provider="<provider-id>", user_token=jwt, url=..., method=...)
except NoDelegatedGrantError as e:
    session = await vault.create_connect_session_for_error(
        e,
        allowed_origin="https://app.example.com",
    )
    # Surface session.connect_url to the user — popup, redirect,
    # out-of-band message, whatever your framework does.
    results = await vault.poll_connect_session(session.session_token)
    # Retry with the freshly-minted grant_id.
    response = await vault.request(grant_id=results[0].grant_id, url=..., method=...)

create_connect_session_for_error and poll_connect_session are available on both App and Agent so the catch block can recover from whichever client raised.

NoDelegatedGrantError and GrantNotFoundError carry provider_id / agent_id / app_user_id recovery context when the original lookup was identity-mode; CredentialRevokedError carries provider_id / app_user_id. See the error reference for the full surface.

Onward delegation (agent to agent)

An agent that holds a grant can hand a scoped-down copy to another agent — without asking the credential owner to consent again. Use agent.delegate() to mint a child grant for the second agent:

from alter_sdk import Agent, GrantNotDelegableError

agent = Agent(api_key="<agent-api-key>")

try:
    result = await agent.delegate(
        "<grant-id>",              # a grant this agent already holds
        "<other-agent-id>",        # the agent that should receive access
        scope_constraint=["chat:write"],   # optional: narrow to fewer scopes
        ttl_seconds=3600,                  # optional: shorten the lifetime
        delegable=False,                   # may the recipient delegate onward? (default no)
    )
    print(result.grant_id, result.depth, result.expires_at)
except GrantNotDelegableError:
    # The held grant was not marked delegable when it was created,
    # so it cannot be passed on. Ask the owner for a delegable grant.
    ...

The held grant must have been created as delegable (chosen at connect time). The child can only narrow — fewer scopes, a shorter lifetime — never widen. A grant narrowed with scope_constraint is proxy-only: call it with agent.proxy_request(...). Onward delegation is opt-in at every hop: pass delegable=True only when the recipient should be allowed to delegate further.

agent.list_grants() returns each grant with parent_grant_id (the grant it was minted under, or None for a root) and depth (its distance from the root), so the full delegation chain can be reconstructed from the flat list.

OpenTelemetry trace propagation

When the application runs an OpenTelemetry SDK, Alter requests automatically carry the active span's W3C traceparent, so the audit trail — and any spans the organization streams to its own OTLP collector — join the application's traces. No configuration is required and opentelemetry is never installed by the SDK itself — it uses whatever OpenTelemetry the application installed; without it (or without an active span) the SDK behaves exactly as before. (The optional alter-sdk[otel] extra is available to record the supported opentelemetry-api version range in the application's dependency tree.)

from opentelemetry import trace

tracer = trace.get_tracer("the-application")

# Inside an async function; `vault` from the quick start above.
with tracer.start_as_current_span("handle-user-request"):
    # This call's audit events share the surrounding trace's ids.
    response = await vault.request(HttpMethod.GET, url, grant_id=grant_id)

Documentation

Full docs are at https://docs.alterauth.com.

Topic	Page
Getting started end-to-end	Quickstart
The mental model	How Alter works
Calling APIs on behalf of users (OAuth + JWT)	Guide
Identity provider setup	Auth0 / Clerk / Okta / WorkOS / Custom OIDC
Provisioning backend secrets	Guide
Scoped credentials for AI agents	Guide
Human-in-the-loop approvals	Guide
OpenTelemetry trace propagation	Calling APIs
Runtime modes (retrieve vs proxy)	Concept
Integrating with Claude Code (MCP)	Guide
Per-method API reference	Python SDK reference
Errors	Error reference

License

MIT. See LICENSE.

Support

Email [e-mail] or open an issue at https://github.com/alter-ai/alter-vault.