Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What Are OAuth Connections?

OAuth grants let end users authorize access to their accounts on third-party services like Google, Slack, GitHub, and more. When a user completes the OAuth flow, Alter Vault stores their tokens securely and provides a grant_id to make API calls on their behalf. Application code never sees or handles OAuth tokens. A call to vault.request(method, url, grant_id=grant_id) is all that is needed and the SDK injects the right credential automatically, refreshing expired tokens transparently.

​
When to Use OAuth

Use OAuth grants when:
  • End users need to authorize access to their accounts (e.g., a user’s Google Calendar, a user’s Slack workspace)
  • You need per-user credentials (each user gets their own grant_id)
  • The service supports OAuth 2.0 and you want automatic token refresh
  • Users should be able to see and revoke their connections via the Wallet Dashboard

​
How It Works

1

User Authorizes

The end user completes the OAuth flow via Alter Connect (popup, redirect, or headless). They log into their account and grant permissions.
2

You Get a grant_id

The onSuccess callback (or connect() return value) provides a grant_id (UUID) for the user’s connected account. Store this in the application database mapped to the user.
3

Tokens Stored Securely

Access tokens, refresh tokens, and expiry data are encrypted (AES-256-GCM) and stored in Alter Vault — never in the application database.
4

Make API Calls

Call vault.request(method, url, grant_id=grant_id) — the SDK retrieves the token, refreshes it if needed, and injects it as the correct auth header.

​
Quick Example

from alter_sdk import AlterVault, HttpMethod

async with AlterVault(
    api_key="alter_key_...",
    caller="my-agent",
) as vault:
    # grant_id from Alter Connect (stored in your DB)
    response = await vault.request(
        HttpMethod.GET,
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        grant_id=grant_id,
        query_params={"maxResults": "10"},
    )
    events = response.json()

​
Three Ways to Trigger OAuth

MethodBest forHow it works
Headless (vault.connect())CLI tools, scripts, Jupyter notebooks, AI agentsOne SDK call does everything — creates a session, opens the browser, and polls until complete. No frontend needed.
RedirectServer-rendered apps, email linksBackend calls create_connect_session() and redirects the user to the returned connect_url. After OAuth, the user is sent back to the return_url. No JS SDK needed.
Popup (@alter-ai/connect)SPAs (React, Vue, etc.)Backend calls create_connect_session() and passes the session_token to the frontend SDK, which opens a popup with onSuccess/onError callbacks.
See the Quickstart for full examples of each method.

​
Key Features

  • Automatic token refresh — tokens are refreshed transparently before they expire
  • Grant policy (TTL) — set maximum grant lifetimes with grant_policy
  • Per-user grants — each user who authorizes gets their own grant_id
  • Multi-account support — users can connect multiple accounts to the same provider (e.g., personal + work Gmail)
  • Wallet visibility — users can see and revoke their connections via the Wallet Dashboard
  • Policy enforcement — time-based and IP-based access rules on every token retrieval
  • Full audit trail — every token access is logged with actor identity, method, URL, and reason

​
Supported OAuth Providers

Alter Vault supports 50+ OAuth providers across categories including productivity, CRM, design, marketing, communication, social, storage, finance, payments, and more. See the OAuth Providers section in the sidebar for the full list and setup guides.

​
Next Steps

Quickstart

Full integration walkthrough

Python SDK

Python SDK quickstart

Alter Connect

Frontend popup SDK

Managed Secrets

For developer-owned API keys and service tokens