Skip to main content

Email Auth

Email Auth lets a user authenticate their Turnkey account via email.

User Experience​

Email auth starts with a new activity posted to Turnkey. This activity has the type ACTIVITY_TYPE_EMAIL_AUTH and takes the following as parameters:

  • email: the email of the user who would like to authenticate. This email must be the email already attached to the user in organization data (i.e., previously approved by the user). This prevents malicious account takeover. If you try to pass a different email address, the activity will fail.
  • targetPublicKey: the public key to which the recovery credential is encrypted (more on this later)
  • apiKeyName: an optional name for the API Key. If none is provided, we will default to Email Auth - <Timestamp>
  • expirationSeconds: an optional window (in seconds) indicating how long the API Key should last. Default to 30 minutes.
  • emailCustomization: optional parameters for customizing emails. If not provided, use defaults. This is currently a WIP. 🚧

This activity generates a new API key pair (an "auth credential"), saves the public key in organization data under the target user, and sends an email with the encrypted auth credential:

Calling email auth requires proper permissions via policies or being a parent organization. See Authorization for more details.

Authorization​

Authorization for email auth is based on our usual activity authorization: our policy engine controls who can and cannot execute recovery-related activities.

  • ACTIVITY_TYPE_EMAIL_AUTH can be performed by the root user or by any user in an organization if authorized by policy, but only if the feature is enabled. The activity can target any user in this organization or any sub-organization user. The activity will fail if a parent user tries to perform email auth for a sub-organization which has opted out of this feature.

Email recovery in your sub-organizations​

Email recovery works well with sub-organizations. Our Demo Passkey Wallet application (https://wallet.tx.xyz) has recovery functionality integrated. We encourage you to try it (and look at the code if you're curious!).

If you're looking for a more concrete guide, head to our Sub-Organization Recovery implementation guide for more details.

Email recovery in your organization​

If you want to use email recovery in the context of an organization accessed via our dashboard, we aren't ready yet. This is because we do not have a flow to enroll new passkeys and sign RECOVER_USER activities in our main dashboard.

A workaround if you're a root user trying to perform recovery for one of your users: delete their user and re-invite them by email. It's not perfect because their new user ID will differ from their old one (which means policies might need an update).

If you're a root user and you have lost access to your authenticators, Turnkey cannot perform email recovery for you. You need to create a fresh organization.

Opting out of email auth​

Similar to email recovery, depending on your threat model, it may be unacceptable to rely on email as an authentication factor. We envision this to be the case when an organization has a mature set of root users with multiple authenticators, or when a sub-organization "graduates" from one to many redundant passkeys or API keys. When you're ready, you can disable email auth with ACTIVITY_TYPE_REMOVE_ORGANIZATION_FEATURE (see Remove Organization Feature). The feature name to remove is FEATURE_NAME_EMAIL_AUTH.

If you never want to have email recovery enabled, our CREATE_SUB_ORGANIZATION activity takes a disableEmailAuth boolean in its parameters. Set it to true and the sub-organization will be created without the organization feature.

Cryptographic details​

Unlike typical email recovery functionality, Turnkey's email recovery doesn't send unencrypted tokens via emails. This ensures no man-in-the-middle attack can happen: even if the content of the auth email is leaked, an attacker wouldn't be able to decrypt the auth credential. The following diagram summarizes the flow:

Our email auth flow works by anchoring auth in a target encryption key (TEK). This target encryption key is a standard P-256 key pair and can be created in many ways: completely offline, or online inside of script using the web crypto APIs.

The public part of this key pair is passed as a parameter inside of a signed EMAIL_AUTH activity. The signature on the activity has to come from a user who is authorized to initiate email auth.

Our enclave creates a fresh P256 key pair ("auth credential") and encrypts the private key to the recovering user's TEK using the Hybrid Public Key Encryption standard, also known as HPKE or RFC 9180.

Once the encrypted auth credential is received via email, it's decrypted where the target public key was originally created. The auth credential is then ready to be used to sign an activity, which is then submitted to Turnkey.

Implementation notes​

Users currently have a limit of 10 long-lived API keys, and 10 expiring API keys. In the case that the limit of expiring API keys is breached, the oldest (by creation date) will be discarded.

NOTE: feature must be enabled. For top-level orgs, by default, Email Auth is not enabled. It must be enabled using a command like

turnkey request --host api.turnkey.com --path /public/v1/submit/email_auth --body '{
                "timestampMs": "'"$(date +%s)"'000",
                "type": "ACTIVITY_TYPE_SET_ORGANIZATION_FEATURE",
                "organizationId": "55205413-cbc2-4b46-94d7-899d3f299b40",
                "parameters": {
                        "name": "FEATURE_NAME_EMAIL_AUTH"
                }
        }' --organization 55205413-cbc2-4b46-94d7-899d3f299b40

Suborgs have Email Auth enabled as a feature by default. It can be conveniently disabled during creation, using the CreateSubOrganizationIntentV4 activity parameter disableEmailAuth.