Here’s how (and why) we built native MFA and Scoped Sessions at Turnkey

We built MFA and Scoped Sessions so teams can easily and securely define exactly what users must prove, what each session can do, and when that authority expires.

Our design offers native controls that work with Turnkey’s existing authentication methods and policy engine, eliminating the need to simulate MFA through proxy users, temporary API keys, and consensus policy chains.

In the past, we’ve had customers who needed multi-factor authentication and technically, Turnkey could support it. But the problem was that it was difficult to build.

Even a simple requirement like “require an email code and a passkey to log in” demanded a complex architecture of proxy users, policies, and approval flows. And adding a second requirement for wallet export made it considerably harder.

Previously, teams could also enforce a second factor in their application’s UI that looked like MFA to end users. This was an easier solution, but because the API did not require it, it allowed for the possibility that that check could be bypassed.

Our goal was to make secure authentication easier to implement, so builders could enforce these requirements directly through the API without constructing a separate architecture around every authentication flow. 

Why MFA and sessions workarounds couldn’t scale

Before native MFA and Scoped Sessions, workarounds for this problem were much more difficult and became even more complex once different activities required different levels of proof. 

They worked, in the narrow sense that the system could eventually produce the intended result, but they also introduced several issues: 

• The users in the system no longer represented actual users.
• One login required multiple identities, policies, and intermediate activities.
• Adding another factor meant adding more entities and approval paths.
• Supporting many end users multiplied the number of relationships a team had to maintain.
• Teams also could not use root users, since their unrestricted permissions bypassed these controls. Instead, they often had to configure the required users and policies, then disable the root user by removing its API key.

Changing the authentication model required rebuilding the surrounding architecture. The system was flexible, but too complex to manage at scale. 

This is a pattern we’ve learned to take seriously when building infrastructure. If the secure path requires customers to assemble several unrelated concepts in exactly the right order, most of them will choose a simpler path. 

The job is not merely to make stronger control possible. It is to make the control reflect the way teams already think about the requirement. Making stronger authentication technically possible was not enough. We needed to make it practical to implement.

Authenticating at the application level is misaligned with security concerns

The other option for MFA, enforcing that second factor only in the client, is a security problem. Authentication is easy to make convincing in a user interface: a product can show an OTP screen, request a passkey, and display a success state before letting the user continue. 

But the UI is not the security boundary. If the API will only accept the underlying request with only one of those factors, the second step is just a convention enforced by the client. It’s not a requirement enforced by the system that controls the wallet. 

This is especially important for actions that Turnkey handles like exporting private keys or moving a large amount of value.

Our goal was to allow teams to define the requirement once and have Turnkey’s API evaluate it wherever the activity originates. If a policy requires an email OTP and a passkey, both methods must approve the activity. 

This also allows the product experience and the security model to tell the same story. The extra authentication step is not there because the frontend decided to show it. It is there because the activity cannot proceed without it, strengthening the security boundary instead of relying on MFA theater.

Designing MFA and Sessions: Identity, authentication, and authorization

Our useful design insight was to separate identity, authentication, and authorization.

1. Who is making the request? The user and their authenticators establish identity.
2. What must they prove for this activity? MFA policies define the required authentication methods.
3. What may the resulting session do, and for how long? Regular policies and Scoped Sessions bound its authority.

These layers work together, but none replaces the others.

An MFA policy does not grant permission to perform an activity. It adds proof requirements to an activity the user must already be authorized to perform. Passing MFA cannot turn an unauthorized request into an authorized one.

A Session Profile also cannot expand a user's permissions. It defines a narrower, preset scope that a user can request when logging in, along with a forced expiration if the parent organization sets one. The session remains bound by the organization's regular policies.

That distinction gives us a clean way to compose the controls. Policies, in general, answer whether an activity is allowed. MFA policies answer which authentication methods must approve it. Scoped Sessions determine how much authority a login session receives and how long that authority lasts.

We did not need to introduce a parallel permission system. We made the existing system expressive enough to describe the complete decision.

MFA requirements now attach directly to activities

MFA policies use the same policy language teams already use in Turnkey. 

Because the requirement applies to the activity itself, MFA is not limited to login. A team can apply it to any Turnkey activity, including wallet export, authenticator changes, policy updates, and other sensitive account operations.

It also works across Turnkey's existing user and approval models. Requirements can apply to root or non-root users, and to users participating in activities that already require m-of-n consensus. The MFA layer adds authentication proof without bypassing the consensus or authorization rules underneath it.

This is important because not every action has the same risk. Requiring a passkey for every routine interaction can add friction without materially improving the controls that matter most. Requiring it when a user exports a wallet or changes an authenticator is a much more precise rule.

Scoped Sessions make authority specific and temporary

Historically, sessions were interchangeable. Once a user logged in, the session could exercise whatever permissions that user had under the organization's policies. The way the user authenticated did not change the power of the resulting session.

Scoped Sessions are non-mutable. They let the parent organization define a set of scopes in advance. At login, the user requests one of those profiles. The profile can restrict the session to particular activities and require it to expire after a defined period.

This lets a team express rules such as:

• An SMS-authenticated session can use the product but cannot export a wallet.
• A passkey-authenticated session can access the full set of permitted actions.
• A user who began with SMS can authenticate with their passkey to upgrade their session with export permissions for 15 minutes.
• A lower-risk session can last for the working day while elevated authority disappears after a few minutes.

Forced expiry is another critical addition. A short-lived elevated session limits the period during which stolen or unattended credentials can be used for a sensitive action. The client does not merely promise to discard the session after 15 minutes. The profile makes that expiration part of the session itself.

Authentication, configuration, and complexity

Authentication at scale is inherently complex. Different operations have different consequences. Organizations need fallback methods. Users need recovery paths. Elevated access should expire. Administrative changes may need stronger controls than the transactions users perform every day.

We cannot remove that complexity, but we can put it in the right place.

Before MFA policies and Scoped Sessions, the complexity lived in customer code and organizational structure. Teams modeled factors as users, created intermediate credentials, and depended on the client to coordinate the correct sequence. The security outcome depended on every part of that custom architecture continuing to behave as intended.

Now teams state which methods an activity requires, which scope a session may receive, and when it must expire. Turnkey evaluates those requirements alongside the policies already governing the user and wallet.

For sensitive infrastructure, understandability is extremely valuable. Controls that only one person knows how to operate eventually become controls no one is willing to change. This design makes the system easier to think through. 

A security reviewer can inspect the rule that governs export instead of reconstructing the behavior from several users, API key creation flows, and frontend conditions.

Turnkey: Making security controls composable

When we designed these features, we could have added a separate MFA product with its own permission model, and exceptions. That might have made the feature easier to describe in isolation, but it would have made Turnkey harder to use as a platform.

Instead, we extended the primitives already present in the system. 

Authentication methods provide proof. MFA policies combine that proof for a particular activity. Scoped Sessions scope and expire the resulting access. Regular policies continue to decide what the user is authorized to do.

This gives teams a path from a basic two-factor login to more advanced controls without replacing the original architecture. Most importantly, the API now enforces the same security promise the application makes to its users. 

If you are designing authentication for embedded wallets, employee access, or autonomous systems, start with three questions: what is the user trying to do, what must they prove for that action, and how long should that authority last?

MFA policies and Scoped Sessions let you encode those answers directly in Turnkey.

Learn more about MFA policies and Scoped Sessions, or get started with Turnkey today.‍