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.

By the end of this guide, an application backend calls third-party APIs on behalf of any logged-in user, without storing tokens and without tracking grant_id in the application database. The flow:
  1. The end user clicks Connect Google in the frontend.
  2. Alter Connect runs the OAuth flow and writes a grant bound to that user’s identity.
  3. The backend calls app.request() with the user’s JWT in scope. The SDK resolves the grant from the JWT, refreshes the token, injects it, and returns the response.

​
Prerequisites

  • An app with a alter_key_app_… API key.
  • An identity provider configured for the app (Auth0, Clerk, Okta, or custom OIDC). End users must already be authenticated through the IDP when they reach the backend.
  • A provider configured — this guide uses Google as the example.
  • The Alter SDK installed and the Connect SDK installed in the frontend.

​
Walkthrough

​
1. Mint a Connect session on the backend

When the user clicks Connect Google in the frontend, the frontend asks the backend for a short-lived session token. The backend mints it via the SDK: 
@app.post("/api/connect-session")
async def create_session(user = Depends(authenticated_user)):
    session = await alter.create_connect_session(
        allowed_providers=["google"],
        allowed_origin="https://app.example.com",
        user_token=user.jwt,  # binds the grant to this user
    )
    return {"session_token": session.session_token}
The session token is short-lived, single-use, and locked to the user identity carried by the JWT.

​
2. Open the Connect widget on the frontend

import AlterConnect from "@alter-ai/connect";

const alterConnect = AlterConnect.create();

const { sessionToken } = await fetch("/api/connect-session").then(r => r.json());

await alterConnect.open({
  token: sessionToken,
  onSuccess: (connection) => {
    // Connection is created. No need to store grant_id — the backend
    // resolves it from the user's JWT on every subsequent call.
    console.log("Connected", connection.provider, connection.accountIdentifier);
  },
});
The widget opens a popup (or, on mobile, redirects), runs OAuth, and calls onSuccess with the connection metadata. The grant is now stored in Alter, bound to this user.

​
3. Call the provider from the backend

The backend constructs the SDK once with a user_token_getter that returns the calling user’s JWT. Every request() carries the JWT; the SDK resolves the grant per-call. 
from alter_sdk import App, HttpMethod
from contextvars import ContextVar

current_jwt: ContextVar[str] = ContextVar("current_jwt")

alter = App(
    api_key=os.environ["ALTER_API_KEY"],
    user_token_getter=lambda: current_jwt.get(),
)

@app.get("/api/calendar/events")
async def list_events(user = Depends(authenticated_user)):
    current_jwt.set(user.jwt)
    response = await alter.request(
        HttpMethod.GET,
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        provider="google",
    )
    return response.json()
Note the call site: no grant_id, only provider. The backend uses the JWT to find the grant.

​
Patterns

​
Multi-account users

A user can have more than one Google account connected. When app.request(provider="google") matches multiple grants, the SDK raises AmbiguousGrantError with the account identifiers. Prompt the user to pick: 
try:
    response = await alter.request(HttpMethod.GET, url, provider="google")
except AmbiguousGrantError as e:
    chosen = await prompt_user_to_pick(e.account_identifiers)
    response = await alter.request(
        HttpMethod.GET, url, provider="google", account=chosen,
    )

​
Listing the user’s connections

For an in-app “Connected accounts” page, list grants visible to the calling user: 
@app.get("/api/connections")
async def list_connections(user = Depends(authenticated_user)):
    current_jwt.set(user.jwt)
    page = await alter.list_grants()
    return [
        {"provider": g.provider_id, "account": g.account_identifier, "grant_id": g.grant_id}
        for g in page.grants
    ]
The Wallet dashboard at wallet.alterauth.com gives end users this view for free — building a custom version is optional.

​
Revoking a grant from the backend

await alter.revoke_grant(grant_id)
The user is also free to revoke from the Wallet at any time.

​
Troubleshooting

ErrorLikely causeFix
GrantNotFoundErrorThe JWT did not match any grant.The user hasn’t completed Connect yet. Show the Connect widget.
AmbiguousGrantErrorThe user has connected the provider more than once.Pass account=... per the multi-account pattern above.
GrantRevokedError / CredentialRevokedErrorUser revoked in the Wallet or at the provider.Show the Connect widget to re-authorize.
ScopeReauthRequiredErrorThe app added a required scope after the user connected.Show the Connect widget to re-authorize with the new scope set.
PolicyViolationErrorA policy denied the call (time-of-day, IP, rate).Inspect e.policy_error. See Policies.

​
What’s next

Embed the Connect widget

Frontend integration details.

Give an agent scoped access

Let an AI agent call providers on the user’s behalf.

Identity resolution

The three modes in depth.