Step-Up Codes
The emailed one-time codes that confirm a destructive action, how they're stored and limited, and how to require one for your own action.
A step-up code is a 6-digit code emailed to the signed-in user to confirm a destructive action, such as deleting an organization. A stolen session alone can't do it: the attacker would also need the user's inbox.
This page is part of the Authentication documentation.
How It Works
- The user asks for a code. Your action checks they may act on the thing first (e.g.
requireOrganizationActionfor an organization), then calls the sender. Deleting an organization (Settings → Organization → Danger zone, owners only) works this way. - The kit makes a 6-digit code, stores only an HMAC of it, and queues an email to the session user's address (never one from the request).
- The user types the code; the action verifies it before doing anything (
deletionCodes.requirein@kit/organizations). A right code works once. A wrong one counts a try; the third wrong try, or 10 minutes, uses the code up. Every failure gives the sameSTEP_UP_CODE_INVALIDerror on thecodefield, with no reason.
| Rule | Value |
|---|---|
| Expiry | 10 minutes (STEP_UP_CODE_TTL_MINUTES) |
| New codes | 1 a minute and 5 an hour per user (STEP_UP_RESEND_SECONDS, STEP_UP_MAX_CODES_PER_HOUR); past them the request is refused with the wait in seconds |
| Replacing | A new code for the same user, purpose and resource stops the previous one working |
| Binding | A code confirms one purpose for one resource: a code to delete organization A can't delete B |
| Storage | HMAC-SHA256 keyed with BETTER_AUTH_SECRET, over the code and its scope; the code itself is never stored or logged |
| Checking | Constant-time (crypto.subtle.verify); a code is consumed with one conditional UPDATE, so of two concurrent checks at most one succeeds |
| Tries | 3 wrong codes (STEP_UP_MAX_ATTEMPTS) use it up; input that isn't six digits spends no try |
| Daily guesses | 10 wrong codes per user in a day, across codes (STEP_UP_MAX_WRONG_CODES_PER_DAY); past it, no new code until enough of them are a day old. Without it, 5 codes an hour would allow 360 guesses a day |
If queueing the email fails, nothing is stored, so the user can ask again at once instead of waiting a minute.
Why Not Better Auth's OTP
Better Auth's built-ins don't cover this:
emailOTPhas four fixed types (sign-in,email-verification,forget-password,change-email) and doesn't bind a code to a resource.- The
twoFactorOTP only runs inside sign-in. one-time-tokenisn't bound to a purpose or resource; its verify accepts any outstanding token.- A fresh session (
freshAge, used for two-factor and passkey changes) proves a recent sign-in, which a stolen session cookie also has.
So the kit keeps its own codes in @kit/otp.
The Table
step_up_challenge, one row per code sent. Only @kit/otp reads or writes it.
| Column | Holds |
|---|---|
user_id | Who it was sent to (deleted with the user) |
purpose | What it confirms, from the closed list STEP_UP_PURPOSES |
resource_id | What it's for, e.g. the organization's id |
code_hmac | The HMAC, not the code |
attempts | Wrong guesses |
expires_at / consumed_at / created_at | Expiry; when it was used or replaced (null while live); when it was sent |
A partial unique index allows one live code per user, purpose and resource. Used and replaced rows stay, because the hourly and daily limits count them; rows older than 24 hours are deleted the next time that user asks for a code.
The table is defined in packages/otp/src/schema.ts (stepUpChallengeTable(user)) and built in apps/web/db/kit-schema.ts, re-exported by apps/web/db/schema.ts.
Requiring a Code for Your Own Action
- Add the purpose to
STEP_UP_PURPOSESinpackages/otp/src/server.ts, e.g.'project-deletion'. - Add an email template for it in
apps/web/config/email-templates.server.tsx(copy inapps/web/messages/<locale>/emails.server.json), onCodeEmailfrom@kit/email-templates. - Add a sender in your own
apps/web/config/*.server.ts, modeled ondeletionCodes.send(packages/organizations/src/deletion-codes.ts): build the step-up service per call withcreateStepUp({ db, table: stepUpChallenge, secret: env.BETTER_AUTH_SECRET })(asgetStepUpinapps/web/config/organizations.server.tsdoes), callissue({ scope, deliver })with the session user, your purpose and your resource id, and queue your template insidedeliver. - Call it from your action after your own permission check, and show
retryAfterSecondswhen it's refused. - Add a check next to it, modeled on
deletionCodes.require: it callsverify({ scope, code })and throwsValidationError({ code: STEP_UP_CODE_INVALID })when it returns false. Call it right before the destructive step, after the permission check; it consumes the code.
Inside deliver, only queue the email: never query the database there. It runs inside the issuing transaction, and the per-request database pool has one connection, so a query would deadlock.
Common Pitfalls
- Issuing before checking the user may act on the resource. The code proves who's asking, not that they're allowed.
- Taking the recipient from the request. The address is always the session user's.
- Logging the code, its HMAC or the queued email body.