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

  1. The user asks for a code. Your action checks they may act on the thing first (e.g. requireOrganizationAction for an organization), then calls the sender. Deleting an organization (Settings → Organization → Danger zone, owners only) works this way.
  2. 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).
  3. The user types the code; the action verifies it before doing anything (deletionCodes.require in @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 same STEP_UP_CODE_INVALID error on the code field, with no reason.
RuleValue
Expiry10 minutes (STEP_UP_CODE_TTL_MINUTES)
New codes1 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
ReplacingA new code for the same user, purpose and resource stops the previous one working
BindingA code confirms one purpose for one resource: a code to delete organization A can't delete B
StorageHMAC-SHA256 keyed with BETTER_AUTH_SECRET, over the code and its scope; the code itself is never stored or logged
CheckingConstant-time (crypto.subtle.verify); a code is consumed with one conditional UPDATE, so of two concurrent checks at most one succeeds
Tries3 wrong codes (STEP_UP_MAX_ATTEMPTS) use it up; input that isn't six digits spends no try
Daily guesses10 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:

  • emailOTP has four fixed types (sign-in, email-verification, forget-password, change-email) and doesn't bind a code to a resource.
  • The twoFactor OTP only runs inside sign-in.
  • one-time-token isn'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.

ColumnHolds
user_idWho it was sent to (deleted with the user)
purposeWhat it confirms, from the closed list STEP_UP_PURPOSES
resource_idWhat it's for, e.g. the organization's id
code_hmacThe HMAC, not the code
attemptsWrong guesses
expires_at / consumed_at / created_atExpiry; 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

  1. Add the purpose to STEP_UP_PURPOSES in packages/otp/src/server.ts, e.g. 'project-deletion'.
  2. Add an email template for it in apps/web/config/email-templates.server.tsx (copy in apps/web/messages/<locale>/emails.server.json), on CodeEmail from @kit/email-templates.
  3. Add a sender in your own apps/web/config/*.server.ts, modeled on deletionCodes.send (packages/organizations/src/deletion-codes.ts): build the step-up service per call with createStepUp({ db, table: stepUpChallenge, secret: env.BETTER_AUTH_SECRET }) (as getStepUp in apps/web/config/organizations.server.ts does), call issue({ scope, deliver }) with the session user, your purpose and your resource id, and queue your template inside deliver.
  4. Call it from your action after your own permission check, and show retryAfterSeconds when it's refused.
  5. Add a check next to it, modeled on deletionCodes.require: it calls verify({ scope, code }) and throws ValidationError({ 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.

Next: Authentication Overview →