Email auth is a powerful feature to couple with sub-organizations for your users. This approach empowers your users to authenticate their Turnkey in a simple way (via email!), while minimizing your involvement: we engineered this feature to ensure your organization is unable to take over sub-organizations even if it wanted to.
auth.turnkey.com
meant to be embedded as an iframe element (see the code here). This ensures the auth credentials are encrypted to keys that your organization doesn’t have access to (because they live in the iframe, on a separate domain)@turnkey/iframe-stamper
yoursite.xyz
clicks “auth”, and a new auth UI is shown. We recommend this auth UI be a new hosted page of your site or application, which contains language explaining to the user what steps they will need to take next to successfully authenticate. While the UI is in a loading state your frontend uses @turnkey/iframe-stamper
to insert a new iframe element:EMAIL_AUTH
activity with the user email and the iframe public key in the parameters. Optional arguments include a custom name for the API key, and a specific duration (denoted in seconds) for it. Note: you’ll need to retrieve the sub-organization ID based on the user email.@turnkey/iframe-stamper
to sign a new activity, e.g. CREATE_WALLET
: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
emailCustomization
variable may look like:
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:
send_from_email_address
or it’s invalid, the other two fields are ignoredsend_from_email_sender_name
is absent, it defaults to “Notifications” (again, ONLY if send_from_email_address
is present and valid)reply_to_email_address
is absent, then there is no reply-to added. If it is present, it must ALSO be from a valid, whitelisted domain, but it doesn’t have to be the same email address as the send_from_email_address
one (though once again, this first one MUST be present, or the other two feature are ignored)whoami
endpoint:
unable to authenticate: api key expired
will be thrown.