# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/step-up-codes*

---

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](./overview).

## 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.

| 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:

- `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.

| 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

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 →](./overview)
