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.

Headless OAuth: a single SDK call opens a browser, walks through OAuth, and returns a grant_id usable immediately. For CLIs, Jupyter notebooks, server-side agents bootstrapping a long-lived grant, or any environment without a frontend to host the Connect.js popup.

​
vault.connect()

Opens the user’s default browser to Alter Connect, polls until they finish OAuth, and returns the resulting grants: 
import asyncio
from alter_sdk import App

async def main():
    vault = App(api_key=ALTER_API_KEY)
    results = await vault.connect(providers=["github"])
    print("grant_id:", results[0].grant_id)
    await vault.close()

asyncio.run(main())
results[0] carries the grant identity and account metadata.
  • In Python: grant_id, provider_id, account_identifier, scopes.
  • In TypeScript: grantId, providerId, accountIdentifier, scopes.
Persist the grant ID somewhere (env var, secret manager, application DB) and pass it to subsequent requests (vault.request(grant_id=...) in Python, vault.request({ grantId: ... }) in TypeScript).

​
Common options

ArgumentWhat it does
providers=[...]Limit which providers the end user can pick. Omit to allow any.
grant_policy={...}Set a max TTL on the resulting grant.
timeout=300How long to poll. Defaults to 5 minutes.
open_browser=FalseDisable auto-open. The SDK prints the connect_url instead — useful for SSH sessions.
Full reference: SDK → Connect (Python) and SDK → Connect (TypeScript).

​
vault.authenticate()

Opens the IDP’s sign-in flow and returns a JWT for the authenticated user. Use this when a script needs to act as a specific user against the JWT-identity flow without persisting a session. 
auth = await vault.authenticate()
print("user:", auth.user_info, "jwt:", auth.user_token)
Requires the app’s IDP to be configured for OIDC sign-in. See OAuth → Identity Providers → Overview.

​
When not to use this

  • Production web apps → use Connect.js for popup flows or create_connect_session() for redirect flows. Headless requires a local browser, which production servers lack.
  • End-user-driven flows already in a session → JWT identity (provider="...", no grant_id needed).

​
Common pitfalls

  • Calling from a remote container. open_browser=True will fail. Set open_browser=False and copy the printed URL into a local browser.
  • Long-running notebooks. The default 5-minute timeout can fire when left unattended. Pass timeout=... for longer windows.
  • SSH session forwarding. SSH X11 forwarding is unreliable for OAuth — print the URL and visit it locally instead.

​
See also