Email Authentication enables users to authenticate and recover their Turnkey accounts using email-based verification. There are two methods of email authentication:
One-Time Password
Credential Bundle
Both methods provide users with an expiring API key for authentication or account recovery.
Email Authentication is built with expiring API keys as the foundation. The two delivery mechanisms are:
The authentication process happens in two steps:
A 6-9 digit or alphanumeric OTP code is sent to the user’s verified email address
Upon verification of the correct code, an API key credential is generated and encrypted for the client
The API key credential is encrypted and delivered directly through email to the user.
In both cases, 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 for more info on how we achieve secure delivery.
Make sure you have set up your primary Turnkey organization with at least one API user that can programmatically initiate email auth on behalf of suborgs. Check out our Quickstart guide 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:
The flow begins with a new activity of type ACTIVITY_TYPE_INIT_OTP_AUTH
with these parameters:
otpType
: specify "OTP_TYPE_EMAIL"
contact
: user’s email address (must match their registered email)emailCustomization
: optional parameters for customizing emailsuserIdentifier
: optional parameter for rate limiting SMS OTP requests per user.
We recommend generating this server-side based on the user’s IP address or public key.
See the OTP Rate Limits section below for more details.alphanumeric
: optional parameter for making this code bech32 alphanumeric or not. default: trueotpLength
: optional parameter for selecting the length of the OTP. default: 9After receiving the OTP, users complete authentication with ACTIVITY_TYPE_OTP_AUTH
:
otpId
: ID from the init activityotpCode
: the 6-9 digit or alphanumeric code received via emailtargetPublicKey
: public key for credential encryptionapiKeyName
: optional name (defaults to OTP Auth - <Timestamp>
)expirationSeconds
: optional validity window (defaults to 15 minutes)invalidateExisting
: optional boolean to invalidate previous OTP Auth API keysIn order to safeguard users, Turnkey enforces rate limits for OTP auth activities. If a userIdentifier
parameter is provided, the following limits are enforced:
userIdentifier
This alternative method uses ACTIVITY_TYPE_EMAIL_AUTH
with these parameters:
email
: user’s email address (must match their registered email)targetPublicKey
: public key for credential encryptionapiKeyName
: optional name (defaults to Email Auth - <Timestamp>
)expirationSeconds
: optional validity window (defaults to 15 minutes)emailCustomization
: optional parameters for customizing emailsinvalidateExisting
: optional boolean to invalidate previous Email Auth API keysFor account recovery scenarios, users can initiate a recovery-specific flow using the ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY
activity type, which requires:
email
: the email of the user needing recovery (must match their registered email)targetPublicKey
: the public key for recovery credential encryptionThe recovery process consists of two phases:
ACTIVITY_TYPE_RECOVER_USER
activity, which can add new authenticators to regain account accessWe offer customization for the following:
appName
: the name of the application. This will be used in the email’s subject, e.g. Sign in to ${appName}
logoUrl
: a link to a PNG with a max width of 340px and max height of 124pxmagicLinkTemplate
: a template for the URL to be used in the magic link button, e.g. https://dapp.xyz/%s
. The auth bundle will be interpolated into the %s
We also support custom HTML email templates for Enterprise clients on the Scale tier. This allows you to inject arbitrary data from a JSON string containing key-value pairs. In this case, the emailCustomization
variable may look like:
In this specific example, the value alice and bob
can be interpolated into the email template using the key username
. The use of such template variables is purely optional.
Here’s an example of a custom HTML email containing an email auth bundle:
If you are interested in implementing bespoke, fully-customized email templates, please reach out to hello@turnkey.com.
Authorization is managed through our policy engine:
Both OTP-based and credential bundle authentication activities:
Specifically:
ACTIVITY_TYPE_INIT_OTP_AUTH
and ACTIVITY_TYPE_OTP_AUTH
ACTIVITY_TYPE_EMAIL_AUTH
ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY
:
ACTIVITY_TYPE_RECOVER_USER
:
Both authentication methods and recovery work seamlessly with sub-organizations.
For implementation details:
For organizations accessed via dashboard:
Ensure the required features are enabled:
FEATURE_NAME_OTP_EMAIL_AUTH
for OTP-based authenticationFEATURE_NAME_EMAIL_AUTH
for credential bundle authenticationUsers initiating the request must have appropriate permissions
Organizations can disable email-based features if their security model requires it:
Use ACTIVITY_TYPE_REMOVE_ORGANIZATION_FEATURE
to disable:
FEATURE_NAME_OTP_EMAIL_AUTH
for OTP-based authenticationFEATURE_NAME_EMAIL_AUTH
for credential bundle authenticationFEATURE_NAME_EMAIL_RECOVERY
for recoveryWhen creating sub-organizations, use:
disableOtpEmailAuth
parameter for OTP-based authenticationdisableEmailAuth
parameter for credential bundle authenticationdisableEmailRecovery
parameter for recoveryUsers are limited to:
ACTIVITY_TYPE_SET_ORGANIZATION_FEATURE
CreateSubOrganizationIntentV7
activity parametersExample of enabling OTP-based Email Auth:
Example of enabling credential bundle Email Auth:
Email Authentication enables users to authenticate and recover their Turnkey accounts using email-based verification. There are two methods of email authentication:
One-Time Password
Credential Bundle
Both methods provide users with an expiring API key for authentication or account recovery.
Email Authentication is built with expiring API keys as the foundation. The two delivery mechanisms are:
The authentication process happens in two steps:
A 6-9 digit or alphanumeric OTP code is sent to the user’s verified email address
Upon verification of the correct code, an API key credential is generated and encrypted for the client
The API key credential is encrypted and delivered directly through email to the user.
In both cases, 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 for more info on how we achieve secure delivery.
Make sure you have set up your primary Turnkey organization with at least one API user that can programmatically initiate email auth on behalf of suborgs. Check out our Quickstart guide 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:
The flow begins with a new activity of type ACTIVITY_TYPE_INIT_OTP_AUTH
with these parameters:
otpType
: specify "OTP_TYPE_EMAIL"
contact
: user’s email address (must match their registered email)emailCustomization
: optional parameters for customizing emailsuserIdentifier
: optional parameter for rate limiting SMS OTP requests per user.
We recommend generating this server-side based on the user’s IP address or public key.
See the OTP Rate Limits section below for more details.alphanumeric
: optional parameter for making this code bech32 alphanumeric or not. default: trueotpLength
: optional parameter for selecting the length of the OTP. default: 9After receiving the OTP, users complete authentication with ACTIVITY_TYPE_OTP_AUTH
:
otpId
: ID from the init activityotpCode
: the 6-9 digit or alphanumeric code received via emailtargetPublicKey
: public key for credential encryptionapiKeyName
: optional name (defaults to OTP Auth - <Timestamp>
)expirationSeconds
: optional validity window (defaults to 15 minutes)invalidateExisting
: optional boolean to invalidate previous OTP Auth API keysIn order to safeguard users, Turnkey enforces rate limits for OTP auth activities. If a userIdentifier
parameter is provided, the following limits are enforced:
userIdentifier
This alternative method uses ACTIVITY_TYPE_EMAIL_AUTH
with these parameters:
email
: user’s email address (must match their registered email)targetPublicKey
: public key for credential encryptionapiKeyName
: optional name (defaults to Email Auth - <Timestamp>
)expirationSeconds
: optional validity window (defaults to 15 minutes)emailCustomization
: optional parameters for customizing emailsinvalidateExisting
: optional boolean to invalidate previous Email Auth API keysFor account recovery scenarios, users can initiate a recovery-specific flow using the ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY
activity type, which requires:
email
: the email of the user needing recovery (must match their registered email)targetPublicKey
: the public key for recovery credential encryptionThe recovery process consists of two phases:
ACTIVITY_TYPE_RECOVER_USER
activity, which can add new authenticators to regain account accessWe offer customization for the following:
appName
: the name of the application. This will be used in the email’s subject, e.g. Sign in to ${appName}
logoUrl
: a link to a PNG with a max width of 340px and max height of 124pxmagicLinkTemplate
: a template for the URL to be used in the magic link button, e.g. https://dapp.xyz/%s
. The auth bundle will be interpolated into the %s
We also support custom HTML email templates for Enterprise clients on the Scale tier. This allows you to inject arbitrary data from a JSON string containing key-value pairs. In this case, the emailCustomization
variable may look like:
In this specific example, the value alice and bob
can be interpolated into the email template using the key username
. The use of such template variables is purely optional.
Here’s an example of a custom HTML email containing an email auth bundle:
If you are interested in implementing bespoke, fully-customized email templates, please reach out to hello@turnkey.com.
Authorization is managed through our policy engine:
Both OTP-based and credential bundle authentication activities:
Specifically:
ACTIVITY_TYPE_INIT_OTP_AUTH
and ACTIVITY_TYPE_OTP_AUTH
ACTIVITY_TYPE_EMAIL_AUTH
ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY
:
ACTIVITY_TYPE_RECOVER_USER
:
Both authentication methods and recovery work seamlessly with sub-organizations.
For implementation details:
For organizations accessed via dashboard:
Ensure the required features are enabled:
FEATURE_NAME_OTP_EMAIL_AUTH
for OTP-based authenticationFEATURE_NAME_EMAIL_AUTH
for credential bundle authenticationUsers initiating the request must have appropriate permissions
Organizations can disable email-based features if their security model requires it:
Use ACTIVITY_TYPE_REMOVE_ORGANIZATION_FEATURE
to disable:
FEATURE_NAME_OTP_EMAIL_AUTH
for OTP-based authenticationFEATURE_NAME_EMAIL_AUTH
for credential bundle authenticationFEATURE_NAME_EMAIL_RECOVERY
for recoveryWhen creating sub-organizations, use:
disableOtpEmailAuth
parameter for OTP-based authenticationdisableEmailAuth
parameter for credential bundle authenticationdisableEmailRecovery
parameter for recoveryUsers are limited to:
ACTIVITY_TYPE_SET_ORGANIZATION_FEATURE
CreateSubOrganizationIntentV7
activity parametersExample of enabling OTP-based Email Auth:
Example of enabling credential bundle Email Auth: