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.

An OAuth grant is what an end user creates when they click “Connect Google” — a stored consent record that lets the app call Google APIs as that user. When a user completes OAuth, Alter Vault stores their tokens encrypted in the vault and returns a grant_id. Every subsequent provider call goes through vault.request(method, url, grant_id=...). Application code never sees a token.

​
When to use OAuth grants

  • End users authorize access to their accounts (Google Calendar, Slack workspace, GitHub repo).
  • Per-user credentials are required.
  • The provider supports OAuth 2.0 and automatic token refresh is desired.
For developer-owned credentials (app-owned API keys, service tokens), use Managed Secrets instead.

​
Lifecycle

1

Authorize

The user completes the OAuth flow via Alter Connect. Three triggers exist — see the trigger comparison below. They log into their account and grant the requested scopes.
2

Store

Access tokens, refresh tokens, and expiry are encrypted (AES-256-GCM) and stored in Alter Vault. Never in the application database.
3

Use

Call vault.request(...). The SDK looks up the grant, retrieves and refreshes the token if needed, and injects it into the outgoing call.
4

Revoke

Either the user (in Wallet) or application code (vault.revoke_grant()) ends the grant. Tokens are deleted immediately.

​
Three identity-resolution modes

Once a grant exists, application code picks how the SDK identifies which grant to use on each call. Pages on this site cover the three modes in this canonical order:
ModeBest forPage
JWTProduction apps with logged-in usersJWT identity
grant_idScripts, batch jobs, explicit controlgrant_id identity
HeadlessCLIs, notebooks, agent bootstrapHeadless
See Concepts → Identity resolution for the decision tree.

​
Three ways to trigger OAuth

Distinct from identity resolution above. This is how the user reaches the consent screen — pick one based on the app’s frontend stack:
MethodBest forHow it works
Headless (vault.connect())CLIs, scripts, Jupyter, server-side agentsOne SDK call creates a session, opens a browser, polls until complete.
Redirect (vault.create_connect_session())Server-rendered apps, email linksBackend gets a connect_url; redirects the user there; receives them at return_url.
Popup (@alter-ai/connect)SPAs (React, Vue, …)Backend creates a session, frontend SDK opens a popup with onSuccess/onError.
See SDKs → Connect.js for popup flows; Headless for connect().

​
Quick example

from alter_sdk import App, HttpMethod

vault = App(api_key=ALTER_API_KEY)

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()

​
What’s included out of the box

  • Automatic token refresh before expiry, per-provider.
  • Multi-account support — a user can connect personal + work Gmail; each is a separate grant.
  • Grant policy (TTL) — set max grant lifetimes when creating a Connect session.
  • End-user revocation — users see and revoke grants in Alter Wallet.
  • Policy enforcement — time-based, IP-based, and group-based rules on every retrieval.
  • Full audit trail — every retrieval logs caller, principal, provider, status.

​
See also

JWT identity (recommended)

Drop grant_id and resolve users from the IDP’s JWT.

Managing grants

List, revoke, and audit grants programmatically.

Identity Providers

Wire Auth0, Clerk, Okta, Keycloak, or WorkOS.

Provider directory

Per-provider setup pages (Google, Slack, GitHub, …).