Meet Latchkey

Latchkey extends the authentication code Rails generates, so you can add sign-in methods without replacing your account models.

Where it fits

Start with bin/rails generate authentication. Your app keeps its User, Session, account provisioning, and password-reset flow. Latchkey adds session handling and the sign-in features you enable.

The current development version supports password, email-link and passkey sign-in, session controls, reauthentication, recovery, and optional bot checks. You can use the included pages or customize their presentation.

Explore the features and roadmap, or compare authentication gems before choosing a starting point.

How sign-in works

Each method checks who the person is, then starts a session—the record that keeps their browser signed in. These diagrams describe the unreleased 0.2.0.dev development version; your app enables the methods it needs, and the account’s policy decides which are allowed.

Password: use the account you already have

flowchart TD
    accTitle: Password sign-in
    accDescr: Enter an email address and password. The app checks the password and whether the account may sign in. Accepted credentials start a session; a failed check leaves the browser signed out with a general error.
    A[Enter email and password] --> B[App checks password and account policy]
    B --> C{Checks pass?}
    C -->|Yes| D[Start a signed-in session]
    C -->|No| E[Stay signed out; show a general error]

Latchkey uses your app’s existing password check and adds its shared session handling. A wrong password, an unknown account, and an account that cannot sign in receive the same general error.

Email link: open the message, then confirm

flowchart TD
    accTitle: Email-link sign-in
    accDescr: Request a link for an existing, eligible account. Open the delivered email link and confirm in the app. Latchkey checks the link and account, uses the link once, and starts a session. An expired or used link requires a new request.
    A[Request a sign-in email] --> B[App emails an eligible account]
    B --> C[Open the link and confirm sign-in]
    C --> D{Link and account checks pass?}
    D -->|Yes| E[Use the link once; start a session]
    D -->|No| F[Stay signed out; request a new link]

The request screen does not reveal whether an account exists or an email was sent. Opening a link alone does not use it up; confirmation signs in the browser that submits it. See email-link sign-in for expiry, resending, and optional same-browser checks.

Passkey: approve with your device or security key

flowchart TD
    accTitle: Passkey sign-in
    accDescr: Choose a saved passkey and unlock it with your device or security key. The browser sends a signed response. Latchkey verifies it and the account before starting a session. A rejected response does not sign the person in.
    A[Choose a saved passkey] --> B[Unlock with your device or security key]
    B --> C[Browser sends a signed response]
    C --> D{Passkey and account checks pass?}
    D -->|Yes| E[Start a signed-in session]
    D -->|No| F[Stay signed out]

The browser handles the fingerprint, face, or PIN prompt; your app receives a signed response. A passkey must already be added to the account, and sign-in needs a supported browser with JavaScript. If it is unavailable or the person cancels, they can retry or use another method that their account permits.

Confirm identity before a sensitive action

Reauthentication, also called step-up, asks a signed-in person to verify again when a particular action needs it—for example, removing a passkey. The app checks both how recently they verified and whether the method is allowed for that action.

flowchart TD
    accTitle: Reauthentication for a sensitive action
    accDescr: A signed-in person starts a sensitive action. If the app needs a fresh identity check, they verify with an allowed method and return to the confirmation page. When they submit, the app checks permission and verification again before making the change.
    A[Start a sensitive action] --> B{Fresh, allowed verification exists?}
    B -->|No| C[Verify with a permitted method]
    C -->|Verified| D[Review the confirmation page]
    C -->|Failed or cancelled| G[Leave the account unchanged]
    B -->|Yes| D
    D --> E[Submit; app rechecks permission and verification]
    E -->|Checks pass| F[Make the requested change]
    E -->|Checks fail| G

Only the permitted methods are offered: password, email link, or passkey. Some actions require a passkey; a recent password or email check cannot substitute for it. An email reauthentication link must be confirmed in the browser and session that requested it.

If verification is cancelled, fails, or expires before the final check, the change is not made. Reauthentication returns to a confirmation page; it does not automatically repeat the original action.

Choose a starting point

What your app still owns

Your app creates accounts, decides which accounts may sign in, sends mail through its provider, and operates its database, cache and job queue. Latchkey does not add a registration flow or move passwords into a second account system.

If your login code differs substantially from the Rails generator, review the generated changes and exercise your existing controller hooks before adopting it. SQLite and PostgreSQL have implementation coverage; other databases need their own verification.

Check availability first

These pages describe 0.2.0.dev, an unreleased development checkout. The documented development changes are not yet published as a gem or fully available in the public repository. Setup requires a development checkout containing this work. Features are implemented and locally tested; remote checks, live-service validation and release acceptance remain open. The release status page explains how to follow availability.