Step-up verification

A signed-in session is enough to read a workspace and to edit a variable. It is not enough to hand out access, destroy a credential, rewrite an environment in one shot, or touch the account itself. 43 actions ask you to prove, right then, that the person driving the session is still you. Envless calls that step-up verification, and it applies to a CLI token exactly as it applies to a browser session.

The proof is one code: an emailed code, or, if you have two factor authentication turned on, a code from your authenticator app. Whichever you use, it buys a one hour window in which the rest of the guarded actions run without asking again. The dialog takes six characters, so it does not accept a recovery code, use the emailed code if your phone is not to hand. The CLI prompt takes either.

What it guards#

The list below is the complete one. Every action here is refused with 403 and auth.step_up_required unless a live elevation covers it.

Your account#

Seven actions are scoped to the account rather than to a workspace, and they are the ones that change how you sign in or end the account outright.

API keys#

Webhooks#

Members, roles and product access#

Products, projects and environments#

Variables and versions#

Workspace and encryption#

Billing and the CLI#

Account scope and workspace scope#

Every challenge carries a scope, and the scope decides what it unlocks.

The asymmetry is deliberate. An account elevation is the stronger proof, so it stands in for a workspace one; a workspace elevation does not reach the account. Switch workspaces inside the hour and the next guarded action in the new workspace asks again, unless what you hold is an account elevation.

The two factors it accepts#

Verification accepts a code from either factor, and the dialog decides which one it asks for first.

With two factor authentication on, the dialog opens asking for the app code and offers the emailed code as the alternative underneath. Nothing is mailed unless you pick it, so the ordinary path costs no round trip through your inbox at all. Recovery codes work here too, and each one still burns on use.

How it works#

Passphrase rotation is gated at the lock#

Rotating the workspace passphrase is guarded when you claim the rotation lock, not on the re-encrypt calls that follow it.

That is not an oversight. One rotation is an unbounded fan-out of re-encrypt requests inside a single held lock, sized by how many variables, versions and history entries the workspace holds. An elevation expiring partway through would abandon the run with the workspace split across two encryption keys. Gating the entry point instead means the check happens once, before anything is rewritten, and the run cannot stall on a code prompt. Releasing the lock is not guarded either, so a rotation you abandon can always be cleaned up.

What is not covered#

From the CLI#

Every guarded action the CLI can reach asks for the same code. That covers envless push, envless var rm, envless version restore, the delete subcommands of workspace, product, project and env, envless env expose, envless product update, envless workspace virtual-envs, envless domain claim and envless domain remove, the member, access and role write subcommands. When the server refuses with auth.step_up_required, the command pauses its spinner, requests a code, prompts for it, verifies it, and reruns the refused request once. One code covers the rest of the run and, like the dashboard, the next hour.

✔ Resolving billing
◇ Delete Billing? Its projects, environments and variables go with it.
│ Yes
› Enter the code we emailed you.
◆ Verification code
│ K7M2PX
└
› ✓ Verified. We will not ask again for an hour.
✔ Removed from Acme

With two factor authentication on, the prompt says so and takes an authenticator code or a recovery code in the same field; the server works out which one it got, and an emailed code still works. The prompt repeats on a wrong code up to five times, matching the server's attempt cap, and stops at once if the authenticator path is locked.

Turning it off for a workspace#

A workspace can switch the guard off for itself, under Settings, Verification Codes. It is on for every workspace by default, and the verification dialog itself points members who hold workspace:update at the switch; everyone else sees only the code field. With it off, the 36 workspace-scoped actions above run on a signed-in session or a CLI token alone, in the dashboard and in the CLI, and auth.step_up_required is never answered for that workspace. The seven account-scoped actions are not affected; they are yours, not the workspace's, and keep asking.

Turning it off is itself guarded, and more strictly than anything else: it asks for a new code every time, whether or not you verified something a minute ago. The server answers auth.step_up_fresh_required instead of auth.step_up_required, the dialog opens on a fresh challenge, and the retry only passes if a code was verified within the last two minutes. An elevation you already hold does not count. Turning it back on needs the workspace:update permission and nothing else, because that is the safe direction.

Both directions notify. Every member of the workspace, the person who made the change included, gets an email naming who made it, and the audit log records a workspace.updated event with changes: ["requireStepUp"], which reaches any webhook subscribed to it. The email that announces the guard is off says what to do if nobody on the team meant it: turn it back on, review the team list, and rotate whatever the session that did it could reach.

Operational consequences#

Going deeper#