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.

from alter_sdk import App

​
connect()

Run headless OAuth from a CLI or notebook. Opens a browser, polls until the user finishes.

​
Signature

async def connect(
    *,
    providers: list[str | Provider] | None = None,
    grant_policy: GrantPolicyInput | None = None,
    timeout: float = 300.0,
    poll_interval: float = 2.0,
    open_browser: bool = True,
) -> list[ConnectResult]

​
Parameters

NameDefaultNotes
providersNoneRestrict the picker. None = any allowed by the app config.
grant_policyNoneSet max TTL on the resulting grant.
timeout300.0Seconds to poll before raising ConnectTimeoutError.
poll_interval2.0Seconds between polls.
open_browserTrueSet False over SSH; the SDK prints the URL to copy.

​
Returns

list[ConnectResult] — one per connected account. Each item carries grant_id, provider_id, account_identifier, scopes.

​
Raises

ConnectFlowError, ConnectDeniedError, ConnectTimeoutError, ConnectConfigError.

​
Example

results = await vault.connect(providers=["github"])
print(results[0].grant_id)

​
authenticate()

Open the IDP’s sign-in flow and return the resulting JWT.

​
Signature

async def authenticate(*, timeout: float = 300.0) -> AuthResult

​
Returns

AuthResult with user_token and user_info.

​
Example

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.

​
create_connect_session()

Build a connect URL backend-side; redirect the user there or hand it to a frontend popup SDK.

​
Signature

async def create_connect_session(
    *,
    allowed_providers: list[str | Provider] | None = None,
    return_url: str | None = None,
    allowed_origin: str | None = None,
    metadata: dict[str, str] | None = None,
    grant_policy: GrantPolicyInput | None = None,
) -> ConnectSession

​
Returns

ConnectSession with session_token and connect_url. Pass session_token to the Connect.js SDK or redirect to connect_url.

​
Example

session = await vault.create_connect_session(
    allowed_providers=["google", "slack"],
    return_url="https://app.example.com/oauth/done",
)
return RedirectResponse(session.connect_url)

​
verify_user_token()

Verify a JWT against the configured IDP without making a provider call.

​
Signature

async def verify_user_token(token: str) -> str | None

​
Returns

The verified sub claim, or None if invalid.

​
Example

sub = await vault.verify_user_token(jwt)
if sub is None:
    raise HTTPException(401, "invalid token")

​
See also