Email Recovery is a legacy flow, now superseded by Email Auth, which can used to implement recovery flows and more.
Overview
This process involves using the following Turnkey SDK packages:@turnkey/sdk-server
: Used on the server-side to leverage the parent organization’s public/private API key pair for initializing the email recovery.@turnkey/sdk-browser
: Used on the client-side to complete the email recovery process by adding an end-user passkey.@turnkey/sdk-react
: Used for Next.js applications to initialize the Turnkey SDK.
Implementation
Initialize the Turnkey SDKs
Begin by initializing the Turnkey SDK with your organization ID and the Turnkey API’s base URL on the client-side.Wrap the root layout of your application with the
TurnkeyProvider
providing the required configuration options. This allows you to use the Turnkey client throughout your app via the useTurnkey()
hook.app/layout.tsx
The
NEXT_PUBLIC_ORGANIZATION_ID
should be set to the parent organization ID which can be found in the Turnkey Dashboard.The NEXT_PUBLIC_TURNKEY_RP_ID
should be set to your application’s desired relying party ID; this is typically your domain, or localhost if developing locally. See this page for more details.Server-side Initialization
Initialize the Turnkey SDK on the server-side using the@turnkey/sdk-server
package. This allows you to use the parent organization’s public/private API key pair to initialize the email recovery process securely.
For Next.js, add the
"use server"
directive at the top of the file where you’re initializing the Turnkey server client. This will ensure that the function is executed on the server-side and will have access to the server-side environment variables e.g. your parent organization’s public/private API key pair. For more information on Next.js server actions, see the Next.js documentation on Server Actions and Mutations.app/actions.ts
Initialize the Iframe Client
Next, we’ll initialize theiframeClient
which will create a secure iframe within your application. The iframeClient
must be initialized before beginning the user recovery process, as we’ll need the iframe’s public key as a parameter for the initEmailRecovery
method.
We add the
"use client"
directive to the Recovery component to as react hooks can only be used client-side.app/recovery.tsx
Create a Recovery Function
Next we’ll create a new function calledinitEmailRecovery
that will be used to initialize the email recovery process on the server-side. This method will be called from the client-side with the user’s email and the target public key from the iframe client. Calling the initEmailRecovery
method will trigger an email sent to the user containing a credential bundle which will be used to authenticate the authIframeClient in the next step.
We export the
initEmailRecovery
server action to be called from the client-side.app/actions.ts
Initialize Email Recovery
At this stage, we initialize the email recovery process using the server-side function we created in the previous step. The user will need to paste the credential bundle they receive in their email into your app, which is then used to authenticate theauthIframeClient
via the injectCredentialBundle
method.
1
Import the server action
app/recovery.tsx
2
Add an input field for the user's email
app/recovery.tsx
3
Create a function to initiate the recovery process
app/recovery.tsx
4
Add an input for the credential bundle
app/recovery.tsx
recovery.tsx
recovery.tsx
Create User Passkey
Next, we’ll create a new passkey for the user and associate it with the email that was used in the recovery process. Assuming that the user has successfully received and entered their credential bundle, we generate a passkey to be used authenticate Turnkey requests.1
Add a function to complete the recovery process
We’ll add a new function called
completeRecovery
that will create a new passkey for the user which will be used in the final recovery step.app/recovery.tsx
2
Add a button to call the completeRecovery function
app/recovery.tsx
Complete Email Recovery
Finally, we complete the email recovery process by passing theencodedChallenge
and attestation
from the passkey we previously created to the recoverUser
method. This method will complete the email recovery process and if successful, will return a response containing the authenticator ID of the new passkey authenticator.
app/recovery.tsx
Complete recovery.tsx component
Complete recovery.tsx component
app/recovery.tsx