Skip to content

Email recovery cleanup #521

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
t-vila merged 2 commits into from
Jan 22, 2026
Merged

Email recovery cleanup #521

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
95cd77d
email recovery cleanup
t-vila Jan 20, 2026
78be347
email recovery cleanup v2
t-vila Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 14 additions & 4 deletions authentication/email.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ description: "Email Authentication enables users to authenticate and recover the
- Uses a 6-9 digit or bech32 alphanumeric one-time password sent via email
- Simple, and familiar user experience

#### One-Time Password Sandbox Environment
**One-Time Password Sandbox Environment**

To test OTP codes in our sandbox environment you can use the following:

Expand All @@ -17,7 +17,7 @@ To test OTP codes in our sandbox environment you can use the following:
- Email: [user@example.com](mailto:user@example.com)
- OTP Code: `000000`

**Credential Bundle**
#### Credential Bundle

- Sends an encrypted API key credential directly via email
- Alternative method for specific use cases
Expand All @@ -44,10 +44,20 @@ The authentication process happens in two steps:

### Credential bundle method

**Note:** on web, this method is only supported with the legacy iframe-based flow, if no hard requirement to use encrypted bundles, we suggest to use the IndexedDB-based OTP flow instead.
<Note> This method is only supported by **legacy iframe-based flows** and is not available in the current Turnkey SDKs. </Note>

The API key credential is encrypted and delivered directly through email to the user. Once the credential is live on the client side (within the context of an iframe), it is readily available to stamp (authenticate) requests. See the [enclave to end-user secure channel](/security/enclave-secure-channels) for more info on how we achieve secure delivery.

This flow remains available for existing legacy integrations but is not recommended for new implementations.
As an alternative, we recommend using the email OTP flow, which is fully supported by the current SDKs. An example that sends a magic link using [magicLinkTemplate](https://docs.turnkey.com/authentication/email#email-auth-and-recovery:~:text=height%20of%20124px-,magicLinkTemplate,-%3A%20a%20template%20for) can be found [here](https://github.com/tkhq/sdk/tree/main/examples/magic-link-auth).

### Email Recovery

In Turnkey, email recovery **does not refer to a separate, recovery-only email address** (as commonly used in consumer products, where a recovery email can reset access but cannot itself be used to sign in).
Instead, it means **adding email as an authentication method for a user**. Once added, that user can authenticate using email by default, alongside any other configured authenticators (such as passkeys, social logins or external wallets).

The legacy iframe-based flow using `INIT_USER_EMAIL_RECOVERY` and `RECOVER_USER` still exists for backward compatibility with older integrations. These flows ultimately attach new authentication material (for example, a passkey) to the user. They are being deprecated and **should not be used for new integrations**.

## Prerequisites

Make sure you have set up your primary Turnkey organization with at least one API user that can programmatically initiate email auth and create suborganizations. Check out our [Quickstart guide](/getting-started/quickstart) if you need help getting started. To allow an API user to initiate email auth, you'll need the following policy in your main organization:
Expand All @@ -70,7 +80,7 @@ For OTP Auth signup and login flows you will need a user with the following poli
}
```

**Note:** Avoid using an API key that is also present in the sub-organization that you're targeting within the email activities. Turnkey identifies the user from the request signature and in case of an identical API key it will always prioritize the sub-organization user matching. As a result, it will try to evaluate the sub-organization policies instead of the parent ones.
<Note>Avoid using an API key that is also present in the sub-organization that you're targeting within the email activities. Turnkey identifies the user from the request signature and in case of an identical API key it will always prioritize the sub-organization user matching. As a result, it will try to evaluate the sub-organization policies instead of the parent ones.</Note>

## User experience

Expand Down
1 change: 0 additions & 1 deletion concepts/organizations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ Organization features are Turnkey product offerings that organizations can opt-i
All activity requests are subject to enforcement by Turnkey's policy engine. The policy engine determines if a request is allowed by checking the following:

- Does this request violate our feature set?
- Email recovery cannot be initiated if disabled
- Email auth cannot be initiated if disabled
- Should this request be denied by default?
- All import requests must target your own user
Expand Down
2 changes: 1 addition & 1 deletion concepts/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ An organization is a logical grouping of resources like users, policies, and wal
| Organization type | Description |
| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Parent Organization | When you first setup your implementation of Turnkey by signing up on the dashboard you create a parent organization controlled by your business. In most implementations, a top-level organization represents an entire Turnkey-powered implementation. For more information on Turnkey parent organizations [look here](/concepts/organizations). |
| Sub-Organization | A fully segregated organization nested under the parent organization. Parent organizations have read access to all their sub-organizations, but do not have write access. Each sub-organization typically maps to an individual end user in a Turnkey-powered application. Parent organizations can initiate limited actions for sub-organizations that then must be completed by the sub-organization, or without the need for completion by the sub-organization (e.g. `INIT_OTP_AUTH` or `INIT_USER_EMAIL_RECOVERY` require completion by sub-organization, `EMAIL_AUTH` does not). For more information on Turnkey sub-organizations [look here](/concepts/sub-organizations). |
| Sub-Organization | A fully segregated organization nested under the parent organization. Parent organizations have read access to all their sub-organizations, but do not have write access. Each sub-organization typically maps to an individual end user in a Turnkey-powered application. Parent organizations can initiate limited actions for sub-organizations that then must be completed by the sub-organization (e.g. `INIT_OTP`). For more information on Turnkey sub-organizations [look here](/concepts/sub-organizations). |

### Users

Expand Down
9 changes: 6 additions & 3 deletions concepts/policies/language.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ The language is strongly typed which makes policies easy to author and maintain.
| | credential_id | string | The credential ID of a passkey. Note: this is only populated for passkeys (also known as Authenticators within Turnkey resources), not API keys |
| | public_key | string | The public key of the credential that approved the request |
| **Activity** | type | string | The type of the activity (e.g. ACTIVITY_TYPE_SIGN_TRANSACTION_V2) |
| | resource | string | The resource type the activity targets: `USER`, `PRIVATE_KEY`, `POLICY`, `WALLET`, `ORGANIZATION`, `INVITATION`, `CREDENTIAL`, `CONFIG`, `RECOVERY`, `AUTH`, `OTP`, `PAYMENT_METHOD`, `SUBSCRIPTION` |
| | resource | string | The resource type the activity targets: `USER`, `PRIVATE_KEY`, `POLICY`, `WALLET`, `ORGANIZATION`, `INVITATION`, `CREDENTIAL`, `CONFIG`, `**RECOVERY`, `AUTH`, `OTP`, `PAYMENT_METHOD`, `SUBSCRIPTION` |
| | action | string | The action of the activity: `CREATE`, `UPDATE`, `DELETE`, `SIGN`, `EXPORT`, `IMPORT` |
| | params | string | The parameters of the activity: `SIGN_RAW_PAYLOADS`, `SIGN_RAW_PAYLOAD_V2` - `hash_function`, `encoding` |
| **Wallet** | id | string | The identifier of the wallet |
Expand Down Expand Up @@ -134,7 +134,7 @@ The language is strongly typed which makes policies easy to author and maintain.
| | outputs | list\<BitcoinTxOutput\> | All outputs created by this Bitcoin transaction |
| | locktime | BitcoinTxLocktime | The locktime of this bitcoin transaction |

\*\*NOTE: The `ContractArgument` type, used in documentation for ABI an IDL arguments represents an enum indicating this type could be any one of the string, number, array or struct types listed in our Primitives section.
<Note> The `ContractArgument` type, used in documentation for ABI an IDL arguments represents an enum indicating this type could be any one of the string, number, array or struct types listed in our Primitives section. </Note>

#### Nested Structs

Expand Down Expand Up @@ -259,7 +259,7 @@ The language is strongly typed which makes policies easy to author and maintain.
| | DELETE | ACTIVITY_TYPE_DELETE_PAYMENT_METHOD |
| **SUBSCRIPTION** | CREATE | ACTIVITY_TYPE_ACTIVATE_BILLING_TIER |
| **CONFIG** | UPDATE | ACTIVITY_TYPE_UPDATE_ALLOWED_ORIGINS |
| **RECOVERY** | CREATE | ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY |
Copy link
Contributor

@ethankonk ethankonk Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here

| ****RECOVERY** | CREATE | ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY |
| **AUTH** | CREATE | ACTIVITY_TYPE_EMAIL_AUTH_V2 |
| | CREATE | ACTIVITY_TYPE_INIT_OTP_AUTH |
| | CREATE | ACTIVITY_TYPE_OTP_AUTH |
Expand All @@ -268,6 +268,9 @@ The language is strongly typed which makes policies easy to author and maintain.
| **OTP** | CREATE | ACTIVITY_TYPE_INIT_OTP |
| | VERIFY | ACTIVITY_TYPE_VERIFY_OTP |


<Note> ** Legacy features, deprecated in the latest SDKs. </Note>

## Appendix

### Policy evaluation
Expand Down