Authentication interactions

Interactions are server-managed transactions used by the Raha-hosted authorization UI. They preserve PKCE, redirect, prompt, locale, remembered-account, login/signup, MFA, and consent state.

Lifecycle

An interaction has a phase: LOGIN, SIGNUP, CONSENT, COMPLETED, FAILED, or CANCELLED. Login and signup expose more specific step state and safe flow data such as masked destinations, available factors, accounts, profiles, and resend timing.

Interaction routes

Method	Route	Purpose
POST	/api/v1/auth/interactions	Start an interaction from an OIDC authorization request.
GET	/api/v1/auth/interactions/{id}	Read current phase, state, client, expiry, and safe flow data.
POST	/api/v1/auth/interactions/{id}/account-selections/{account_id}	Continue with a remembered account.
DELETE	/api/v1/auth/interactions/{id}/accounts/{account_id}	Remove a remembered account from the account set.
POST	/api/v1/auth/interactions/{id}/account-logins	Start login for another account.
POST	/api/v1/auth/interactions/{id}/signup-conversion	Convert the transaction to signup.
POST	/api/v1/auth/interactions/{id}/login-conversion	Convert the transaction to login.
DELETE	/api/v1/auth/interactions/{id}	Cancel the transaction.

Step actions live under /api/v1/auth/interactions/{id}/login/..., /signup/..., and /consent-decisions. Successful completion returns a validated redirect_to containing the authorization response.

Security behavior

Interaction responses use Cache-Control: no-store. Session and account-set cookies are HTTP-only controls owned by the identity provider. Never place credentials, OTPs, recovery codes, or tokens in logs or URLs.