title: auth sidebarTitle: auth#
backend.api.auth#
authentication api endpoints.
Functions#
get_pds_options source#
get_pds_options() -> PdsOptionsResponse
get available PDS options for account creation.
returns the list of recommended PDS hosts where users can create new ATProto accounts. this is used by the frontend login page to show the "create account" option.
start_login source#
start_login(request: Request, handle: str | None = None, pds_url: str | None = None) -> RedirectResponse
start OAuth flow for login or account creation.
for login: provide handle to authenticate with an existing account.
for account creation: provide pds_url to create a new account on that PDS.
exactly one of handle or pds_url must be provided.
oauth_callback source#
oauth_callback(code: Annotated[str, Query()], state: Annotated[str, Query()], iss: Annotated[str, Query()]) -> RedirectResponse
handle OAuth callback and create session.
returns exchange token in URL which frontend will exchange for session_id. exchange token is short-lived (60s) and one-time use for security.
handles four flow types based on pending state:
- developer token flow - creates dev token session, redirects with dev_token=true
- scope upgrade flow - replaces old session with new one, redirects to settings
- add account flow - creates session in existing group, redirects to portal
- regular login flow - creates session, redirects to portal or profile setup
exchange_token source#
exchange_token(request: Request, exchange_request: ExchangeTokenRequest, response: Response) -> ExchangeTokenResponse
exchange one-time token for session_id.
frontend calls this immediately after OAuth callback to securely exchange the short-lived token for the actual session_id.
for browser requests: sets HttpOnly cookie and still returns session_id in response for SDK/CLI clients: only returns session_id in response (no cookie) for dev token exchanges: returns session_id but does NOT set cookie
logout source#
logout(session: Session = Depends(require_auth), switch_to: Annotated[str | None, Query(description='DID to switch to after logout')] = None, db = Depends(get_db)) -> JSONResponse
logout current user.
if switch_to is provided and valid, deletes current session and switches to the specified account. otherwise, fully logs out.
get_current_user source#
get_current_user(session: Session = Depends(require_auth), db = Depends(get_db)) -> CurrentUserResponse
get current authenticated user with linked accounts.
get_developer_tokens source#
get_developer_tokens(session: Session = Depends(require_auth)) -> DeveloperTokenListResponse
list all developer tokens for the current user.
delete_developer_token source#
delete_developer_token(token_prefix: str, session: Session = Depends(require_auth)) -> JSONResponse
revoke a developer token by its prefix (first 8 chars of session_id).
start_developer_token_flow source#
start_developer_token_flow(request: Request, body: DevTokenStartRequest, session: Session = Depends(require_auth)) -> DevTokenStartResponse
start OAuth flow to create a developer token with its own credentials.
this initiates a new OAuth authorization flow. the user will be redirected to authorize, and on callback a dev token with independent OAuth credentials will be created. this ensures dev tokens don't become stale when browser sessions refresh their tokens.
returns the authorization URL that the frontend should redirect to.
start_scope_upgrade_flow source#
start_scope_upgrade_flow(request: Request, body: ScopeUpgradeStartRequest, session: Session = Depends(require_auth)) -> ScopeUpgradeStartResponse
start OAuth flow to upgrade session scopes.
this initiates a new OAuth authorization flow with expanded scopes. the user will be redirected to authorize, and on callback the old session will be replaced with a new session that has the requested scopes.
use this when a user enables a feature that requires additional OAuth scopes (e.g., enabling teal.fm scrobbling which needs fm.teal.alpha.* scopes).
returns the authorization URL that the frontend should redirect to.
start_add_account_flow source#
start_add_account_flow(request: Request, body: AddAccountStartRequest, session: Session = Depends(require_auth)) -> AddAccountStartResponse
start OAuth flow to add another account to the session group.
the user must provide the handle of the account they want to add. this initiates a new OAuth authorization flow with prompt=login to force fresh authentication. the new account will be linked to the same session group as the current account, enabling quick switching between accounts.
returns the authorization URL that the frontend should redirect to.
switch_account source#
switch_account(body: SwitchAccountRequest, response: Response, session: Session = Depends(require_auth), db = Depends(get_db)) -> SwitchAccountResponse
switch to a different account in the session group.
switches the active account within the session group. the cookie is updated to point to the new session, and the old session is marked inactive.
returns the new active account's info.
logout_all source#
logout_all(session: Session = Depends(require_auth), db = Depends(get_db)) -> JSONResponse
logout all accounts in the session group.
removes all sessions in the group and clears the cookie.
Classes#
LinkedAccountResponse source#
account info for account switcher UI.
CurrentUserResponse source#
response model for current user endpoint.
DeveloperTokenInfo source#
info about a developer token (without the actual token).
Methods:
truncate_session_id source#
truncate_session_id(cls, v: str) -> str
truncate to 8-char prefix for safe display.
DeveloperTokenListResponse source#
response model for listing developer tokens.
PdsOption source#
a PDS option for account creation.
PdsOptionsResponse source#
response model for PDS options endpoint.
ExchangeTokenRequest source#
request model for exchanging token for session_id.
ExchangeTokenResponse source#
response model for exchange token endpoint.
DevTokenStartRequest source#
request model for starting developer token OAuth flow.
DevTokenStartResponse source#
response model with OAuth authorization URL.
ScopeUpgradeStartRequest source#
request model for starting scope upgrade OAuth flow.
ScopeUpgradeStartResponse source#
response model with OAuth authorization URL.
AddAccountStartRequest source#
request model for starting add-account flow.
AddAccountStartResponse source#
response model with OAuth authorization URL for adding account.
SwitchAccountRequest source#
request model for switching to a different account.
SwitchAccountResponse source#
response model after switching accounts.