Recovering a password

This is the standard password-recovery flow for users who can sign in with an email and password (typically organisation users — contributors usually sign in with a one-time code instead and don’t have passwords to recover).

What happens

sequenceDiagram
    actor User
    participant App as Your app
    participant Ory as Identity system

    User->>App: Click "Forgot password" on login page
    App-->>User: Recover-password page (email field)
    User->>App: Enter email and submit
    App->>Ory: Request recovery flow
    Ory->>User: Recovery email with 6-digit code
    User->>App: Enter the code
    App->>Ory: Verify code
    Ory-->>App: Code valid, ready to set password
    User->>App: Enter new password (twice)
    App->>Ory: Update password
    Ory-->>App: Done
    App-->>User: Success message

The recovery code is sent by the identity system (Ory), not by your app. The text of the recovery email is configured in Ory, not in your tep-configuration translations.

Step-by-step

Step 1 — Enter email

User lands on the recover-password page (usually from a “Forgot password?” link on the login screen) and is shown an email field.

Visible text	Translation key
Page title	auth.RecoverPassword.title
Instruction	auth.RecoverPassword.instruction
Email field label	auth.common.email-address
”Back to login” link	auth.common.login

Step 2 — Receive recovery email

After submitting, the identity system emails a 6-digit recovery code to the address. If the address isn’t on file, Ory may still respond without revealing whether the email exists — by design, to prevent account-enumeration attacks.

Step 3 — Enter the code

The page swaps to a code-input view with a 6-digit field.

Visible text	Translation key
Reminder text	auth.RecoverPassword.reminder
Code-verified toast (when code is accepted)	auth.RecoverPassword.code-verified

The form will lock further code attempts after 5 failed tries — the user has to restart by re-entering their email. There’s also a 60-second cooldown on the “Resend code” link.

Step 4 — Set new password

Once the code is verified, the page swaps to a new-password form. The user enters a new password (typically with confirmation). Password policy (length, complexity) is enforced by the identity system.

Step 5 — Confirmation

A success message confirms the password has been reset.

Visible text	Translation key
Success message	auth.RecoverPassword.message.success
Password-reset confirmation	auth.RecoverPassword.password-reset-success

The user can then go back to log in with their new password.

What you can customise

Translations (app-side)

All keys above live under auth.RecoverPassword.* in tep-configuration/translations/{locale}/main/auth.json. As with all translations, you can override per client in clients/{client}/translations/{locale}/overrides.json.

The recovery email itself

The recovery email is sent by Ory, not by your app. To customise it:

• Text and templating: configured in your Ory project, not in tep-configuration. Ory provides its own templating system for these emails.
• Branding: same — Ory’s email layout is configured in the Ory dashboard.

This means recovery emails are customised in a different place from your normal app emails. We can supply Ory-customisation guidance separately if you need to localise these.

Known gap

If the recovery flow fails to start (e.g. the identity system is unreachable), the page shows the message “Failed to initialize password recovery. Please refresh the page.” in English. This message isn’t currently localisable.

Variations for your deployment

The recovery flow is the same across all clients. Differences are only in branding and language of:

• The recover-password page text (controlled by your translations)
• The recovery email (controlled in Ory)

Need more detail?

For code paths and engineering notes, see Recovering a password (engineering).