Authentication

Raha Account uses a hosted interaction rather than exposing password collection to relying parties. An authorization request can move through login or signup, MFA, account/profile selection, and consent before returning an authorization code.

Authorization request

Required parameters are client_id, redirect_uri, response_type=code, scope, code_challenge, and code_challenge_method=S256. Production integrations should also send state and nonce.

Supported optional controls include:

• prompt: none, login, consent, select_account, or create.
• acr_values: request an authentication assurance level supported by the client.
• id_token_hint: provide context for an existing OpenID session.
• account_id: suggest a remembered account.
• ui_locales and ui_theme: match the hosted presentation to the client application.

See Authorization UI preferences for locale and theme behavior.

Sessions and remembered accounts

The identity provider maintains its own secure session cookie. A browser may remember more than one account and ask the user to select one. Client applications receive tokens for the completed authorization transaction; they do not receive the IdP cookie.

Revoked sessions and JWT IDs are rejected by protected APIs. A normal logout may leave other remembered accounts available, while logout-all/end-session terminates the broader IdP session and dispatches configured logout notifications.

MFA

The hosted flow supports password, OTP, TOTP, SMS, email, and recovery-code paths when enabled for the account and requested assurance level. Account owners can manage enrolled factors through the account portal API.

First-party interaction APIs

Routes under /api/v1/auth/interactions and /api/v1/auth/interactions/{id}/... drive the Raha-hosted UI. Third-party clients should use the authorization_endpoint and must not reproduce or automate those internal screens.

Password recovery

Password recovery uses a separate challenge, verification, and reset sequence. See Password recovery.