OAuthFlow Class

One named OAuth connection, plus the handlers attached to it.

Created via app.add_oauth_flow(...) — not constructed directly.

Constructor

OAuthFlow(connection_name: str, *, oauth_card_text: str = 'Please Sign In...', sign_in_button_text: str = 'Sign In')

Parameters

Name	Description
connection_name Required

Keyword-Only Parameters

Name	Description
oauth_card_text	Default value: Please Sign In...
sign_in_button_text	Default value: Sign In

Methods

get_token	The user's token for this connection, or None if not signed in.
is_signed_in	Whether the user currently has a token for this connection.
on_signin	Register a handler for a successful sign-in on this connection. The handler may be synchronous or asynchronous, and may be registered more than once. Handlers run in registration order and are isolated from one another: if one raises, the error is logged and the rest still run.
on_signin_failure	Register a handler for a failed silent-SSO attempt on this connection. The handler may be synchronous or asynchronous, and may be registered more than once. Handlers run in registration order and are isolated from one another: if one raises, the error is logged and the rest still run. A signin/failure callback carries no connection name, so the app matches it against the pending sign-in recorded when the flow started. That record lives in durable state when state is enabled, and otherwise in a short-lived process-local cache. If neither resolves — most commonly because the callback reached a different process than the one that started the sign-in — the failure cannot be attributed, and every registered flow's failure handlers are notified rather than none. Handlers that must act on only their own connection should enable state, which makes attribution reliable across processes.
sign_in	Start sign-in. Returns a token immediately if one already exists, otherwise sends an OAuth card and returns None. If the caller passes their own SignInOptions their card text wins, but the connection name is always forced to this flow's — you cannot accidentally sign in on the wrong connection through a flow object. When per-turn state is enabled, a pending hint is recorded so connection-less verify-state callbacks probe likely flows first and silent-SSO failures can be attributed to this flow. Without state, verify-state probes the registered flows and legacy default connection, while failures use the registered-flow fallback.
sign_out	Sign the user out of this connection.

get_token

The user's token for this connection, or None if not signed in.

async get_token(ctx: ActivityContext[Any]) -> str | None

Parameters

Name	Description
ctx Required

is_signed_in

Whether the user currently has a token for this connection.

async is_signed_in(ctx: ActivityContext[Any]) -> bool

Parameters

Name	Description
ctx Required

on_signin

Register a handler for a successful sign-in on this connection.

The handler may be synchronous or asynchronous, and may be registered more than once. Handlers run in registration order and are isolated from one another: if one raises, the error is logged and the rest still run.

on_signin(func: SignInHandlerT) -> SignInHandlerT

Parameters

Name	Description
func Required

on_signin_failure

Register a handler for a failed silent-SSO attempt on this connection.

The handler may be synchronous or asynchronous, and may be registered more than once. Handlers run in registration order and are isolated from one another: if one raises, the error is logged and the rest still run.

A signin/failure callback carries no connection name, so the app matches it against the pending sign-in recorded when the flow started. That record lives in durable state when state is enabled, and otherwise in a short-lived process-local cache. If neither resolves — most commonly because the callback reached a different process than the one that started the sign-in — the failure cannot be attributed, and every registered flow's failure handlers are notified rather than none. Handlers that must act on only their own connection should enable state, which makes attribution reliable across processes.

on_signin_failure(func: SignInFailureHandlerT) -> SignInFailureHandlerT

Parameters

Name	Description
func Required

sign_in

Start sign-in.

Returns a token immediately if one already exists, otherwise sends an OAuth card and returns None. If the caller passes their own SignInOptions their card text wins, but the connection name is always forced to this flow's — you cannot accidentally sign in on the wrong connection through a flow object. When per-turn state is enabled, a pending hint is recorded so connection-less verify-state callbacks probe likely flows first and silent-SSO failures can be attributed to this flow. Without state, verify-state probes the registered flows and legacy default connection, while failures use the registered-flow fallback.

async sign_in(ctx: ActivityContext[Any], options: SignInOptions | None = None) -> str | None

Parameters

Name	Description
ctx Required
options	Default value: None

sign_out

Sign the user out of this connection.

async sign_out(ctx: ActivityContext[Any]) -> None

Parameters

Name	Description
ctx Required