From 71d4301f810346170d48aa40c12fb21ccce998a6 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 25 Nov 2025 21:48:07 +0000 Subject: [PATCH 1/5] Documentation edits made through Mintlify web editor --- authentication/email.mdx | 87 +++++++++++++++++++++++++++++----------- 1 file changed, 64 insertions(+), 23 deletions(-) diff --git a/authentication/email.mdx b/authentication/email.mdx index 7978327a..b40acebd 100644 --- a/authentication/email.mdx +++ b/authentication/email.mdx @@ -14,7 +14,7 @@ To test OTP codes in our sandbox environment you can use the following: - `alphanumeric` must be set to `false` - `otpLength` must be set to `6` -- Email: user@example.com +- Email: [user@example.com](mailto:user@example.com) - OTP Code: `000000` **Credential Bundle** @@ -35,12 +35,10 @@ The authentication process happens in two steps: - A 6-9 digit or alphanumeric OTP code is sent to the user's verified email - address + 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 + Upon verification of the correct code, an API key credential is generated and encrypted for the client @@ -48,8 +46,7 @@ The authentication process happens in two steps: **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. -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. +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. ## Prerequisites @@ -84,9 +81,7 @@ The flow begins with a new activity of type `ACTIVITY_TYPE_INIT_OTP` using the p - `otpType`: specify `"OTP_TYPE_EMAIL"` - `contact`: user's email address - `emailCustomization`: optional parameters for customizing emails -- `userIdentifier`: 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](#otp-rate-limits) section below for more details. +- `userIdentifier`: 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](#otp-rate-limits) section below for more details. - `alphanumeric`: optional parameter for making this code bech32 alphanumeric or not. default: true - `otpLength`: optional parameter for selecting the length of the OTP. default: 9 - `expirationSeconds`: optional validity window (defaults to 5 minutes) @@ -108,10 +103,7 @@ After receiving the verification token, users complete OTP authentication flow w - `invalidateExisting`: optional boolean to invalidate previous login sessions - auth otp email + ![auth otp email](/images/authentication/img/auth_otp_email.png) ### OTP rate limits @@ -134,7 +126,7 @@ This alternative method uses `ACTIVITY_TYPE_EMAIL_AUTH` with these parameters: - `invalidateExisting`: optional boolean to invalidate previous Email Auth API keys - auth email + ![auth email](/images/authentication/img/auth_email.png) ## Email customization @@ -165,6 +157,61 @@ const response = await client.emailAuth({ }); ``` +**Auth Proxy Update: appName becomes a required parameter (12/8/2025)** + + + **Auth Proxy: appName becomes a required parameter** + + \ + Beginning the week of **December 8 2025**, all new versionf of email-based OTP and recovery activities will **require the appName parameter. **Until this point the appName is optional. + + \ + We’re releasing a new major version of our server SDKs which will introduce a **major version bump.** + + - The **appName** will become a **required** field in updated email activities + + Existing SDK versions will continue working, but upgrading without setting an **appName** will break email-based flows.\ + \ + **Who is Affected**\ + **Auth Proxy users**: Anyone using the Auth Proxy without an appName set + + **Server SDK users: ** + + - Users who do not specify an appName, and/or + - Any user calling email-based flows, including: + - Init_otp_auth + - Init_otp + - Email_recovery + - Email_auth + + **What You Will Need To Do** + + **Auth Proxy users:** + + - Ensure there is an **appName** set under email configuration, [here](https://app.turnkey.com/dashboard/walletKit) + + **Server-SDK users:** + + - For those using email_recovery or email_auth + - Ensure you include an **AppName** in your request + - For those using init_otp or init_otp_auth: When upgrading to the newest server-SDK (a major version), you **must** update your API call to match the new input structure + + **If you are using policies to manage email flows:** + + - EMAIL_AUTH  + - **Old activities:** ACTIVITY_TYPE_EMAIL_AUTH, ACTIVITY_TYPE_EMAIL_AUTH_V2 + - **New activity**: ACTIVITY_TYPE_EMAIL_AUTH_V3 + - INIT_OTP_AUTH + - **Old activities**: ACTIVITY_TYPE_INIT_OTP_AUTH, ACTIVITY_TYPE_INIT_OTP_AUTH_V2 + - **New activity**: ACTIVITY_TYPE_INIT_OTP_AUTH_V3 + - INIT_OTP  + - **Old activity**: ACTIVITY_TYPE_INIT_OTP  + - **New activity**: ACTIVITY_TYPE_INIT_OTP_V2 + - INIT_USER_EMAIL_RECOVERY + - **Old activity**: ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY + - **New activity**: ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2 + + ### Email templates We also support custom HTML email templates for [Enterprise](https://www.turnkey.com/pricing) 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: @@ -238,10 +285,7 @@ Specifically: - For credential bundle auth: `ACTIVITY_TYPE_EMAIL_AUTH` - email auth authorization + ![email auth authorization](/images/authentication/img/diagrams/email_auth_authorization.png) ### Example implementations @@ -255,10 +299,8 @@ Specifically: For organizations accessed via dashboard: 1. Ensure the required features are enabled: - - `FEATURE_NAME_OTP_EMAIL_AUTH` for OTP-based authentication - `FEATURE_NAME_EMAIL_AUTH` for credential bundle authentication - 2. Users initiating the request must have appropriate permissions ## Opting out @@ -278,7 +320,6 @@ When creating sub-organizations, use: ## Implementation notes - Users are limited to: - - 10 long-lived API keys - 10 expiring API keys (oldest are discarded when limit is reached) @@ -316,4 +357,4 @@ turnkey request --host api.turnkey.com --path /public/v1/submit/set_organization "name": "FEATURE_NAME_EMAIL_AUTH" } }' --organization -``` +``` \ No newline at end of file From df47988beaf7ba75bf8e8feb96a1f5d3e1168bd4 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 25 Nov 2025 21:54:17 +0000 Subject: [PATCH 2/5] Documentation edits made through Mintlify web editor --- authentication/email.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/authentication/email.mdx b/authentication/email.mdx index b40acebd..42453456 100644 --- a/authentication/email.mdx +++ b/authentication/email.mdx @@ -163,10 +163,7 @@ const response = await client.emailAuth({ **Auth Proxy: appName becomes a required parameter** \ - Beginning the week of **December 8 2025**, all new versionf of email-based OTP and recovery activities will **require the appName parameter. **Until this point the appName is optional. - - \ - We’re releasing a new major version of our server SDKs which will introduce a **major version bump.** + Beginning the week of **December 8 2025**, all new versionf of email-based OTP and recovery activities will **require the appName parameter. **Until this point the appName is optional. We’re releasing a new major version of our server SDKs which will introduce a **major version bump.** - The **appName** will become a **required** field in updated email activities @@ -175,7 +172,7 @@ const response = await client.emailAuth({ **Who is Affected**\ **Auth Proxy users**: Anyone using the Auth Proxy without an appName set - **Server SDK users: ** + **Server SDK users:** - Users who do not specify an appName, and/or - Any user calling email-based flows, including: From 2539e52bb99e70ab93a9db1a1c2558cfd4284493 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 26 Nov 2025 15:14:36 +0000 Subject: [PATCH 3/5] Documentation edits made through Mintlify web editor --- authentication/email.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/authentication/email.mdx b/authentication/email.mdx index 42453456..9f3380b4 100644 --- a/authentication/email.mdx +++ b/authentication/email.mdx @@ -163,7 +163,7 @@ const response = await client.emailAuth({ **Auth Proxy: appName becomes a required parameter** \ - Beginning the week of **December 8 2025**, all new versionf of email-based OTP and recovery activities will **require the appName parameter. **Until this point the appName is optional. We’re releasing a new major version of our server SDKs which will introduce a **major version bump.** + Beginning the week of **December 8 2025**, all new versionf of email-based OTP and recovery activities will **require the appName parameter**. Until this point the appName is optional. We’re releasing a new major version of our server SDKs which will introduce a **major version bump.** - The **appName** will become a **required** field in updated email activities From 1148dfc73622182d0da82163d4cafd783970aade Mon Sep 17 00:00:00 2001 From: Mohammed Odeh Date: Tue, 2 Dec 2025 10:00:18 -0500 Subject: [PATCH 4/5] clean up --- authentication/email.mdx | 78 ++++++++++++++++------------------------ 1 file changed, 31 insertions(+), 47 deletions(-) diff --git a/authentication/email.mdx b/authentication/email.mdx index 9f3380b4..4a00f262 100644 --- a/authentication/email.mdx +++ b/authentication/email.mdx @@ -157,58 +157,42 @@ const response = await client.emailAuth({ }); ``` -**Auth Proxy Update: appName becomes a required parameter (12/8/2025)** +### Breaking Change: `appName` Required - **Auth Proxy: appName becomes a required parameter** + **Effective December 8, 2025** + + Beginning the week of December 8, 2025, all email-based OTP and recovery activities will require the `appName` parameter. Existing SDK versions will continue working, but upgrading without setting an `appName` will break email-based flows. + + + + **Affected:** Anyone using Auth Proxy without `appName` set + + **Action:** Set `appName` under [email configuration](https://app.turnkey.com/dashboard/walletKit) + + + **Affected:** Users calling `init_otp_auth`, `init_otp`, `email_recovery`, or `email_auth` without `appName` + + **Action:**
+ • For `email_recovery` or `email_auth`: include `appName` in your request
+ • For `init_otp` or `init_otp_auth`: update your API call to match the new input structure when upgrading to the latest server-SDK + + + + + If you manage email flows with policies, update to the new activity types: + + | Flow | Old Activities | New Activity | + |------|---------------|--------------| + | EMAIL_AUTH | `ACTIVITY_TYPE_EMAIL_AUTH`, `ACTIVITY_TYPE_EMAIL_AUTH_V2` | `ACTIVITY_TYPE_EMAIL_AUTH_V3` | + | INIT_OTP_AUTH | `ACTIVITY_TYPE_INIT_OTP_AUTH`, `ACTIVITY_TYPE_INIT_OTP_AUTH_V2` | `ACTIVITY_TYPE_INIT_OTP_AUTH_V3` | + | INIT_OTP | `ACTIVITY_TYPE_INIT_OTP` | `ACTIVITY_TYPE_INIT_OTP_V2` | + | INIT_USER_EMAIL_RECOVERY | `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY` | `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2` | + - \ - Beginning the week of **December 8 2025**, all new versionf of email-based OTP and recovery activities will **require the appName parameter**. Until this point the appName is optional. We’re releasing a new major version of our server SDKs which will introduce a **major version bump.** - - - The **appName** will become a **required** field in updated email activities - - Existing SDK versions will continue working, but upgrading without setting an **appName** will break email-based flows.\ - \ - **Who is Affected**\ - **Auth Proxy users**: Anyone using the Auth Proxy without an appName set - - **Server SDK users:** - - - Users who do not specify an appName, and/or - - Any user calling email-based flows, including: - - Init_otp_auth - - Init_otp - - Email_recovery - - Email_auth - - **What You Will Need To Do** - - **Auth Proxy users:** - - - Ensure there is an **appName** set under email configuration, [here](https://app.turnkey.com/dashboard/walletKit) - - **Server-SDK users:** - - - For those using email_recovery or email_auth - - Ensure you include an **AppName** in your request - - For those using init_otp or init_otp_auth: When upgrading to the newest server-SDK (a major version), you **must** update your API call to match the new input structure - - **If you are using policies to manage email flows:** - - - EMAIL_AUTH  - - **Old activities:** ACTIVITY_TYPE_EMAIL_AUTH, ACTIVITY_TYPE_EMAIL_AUTH_V2 - - **New activity**: ACTIVITY_TYPE_EMAIL_AUTH_V3 - - INIT_OTP_AUTH - - **Old activities**: ACTIVITY_TYPE_INIT_OTP_AUTH, ACTIVITY_TYPE_INIT_OTP_AUTH_V2 - - **New activity**: ACTIVITY_TYPE_INIT_OTP_AUTH_V3 - - INIT_OTP  - - **Old activity**: ACTIVITY_TYPE_INIT_OTP  - - **New activity**: ACTIVITY_TYPE_INIT_OTP_V2 - - INIT_USER_EMAIL_RECOVERY - - **Old activity**: ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY - - **New activity**: ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2 + ### Email templates We also support custom HTML email templates for [Enterprise](https://www.turnkey.com/pricing) 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: From c304a8ddfb55cf663cd011814bbe18c9a5308228 Mon Sep 17 00:00:00 2001 From: Mohammed Odeh Date: Tue, 2 Dec 2025 10:53:23 -0500 Subject: [PATCH 5/5] policy card --- authentication/email.mdx | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/authentication/email.mdx b/authentication/email.mdx index 4a00f262..8fdc59d3 100644 --- a/authentication/email.mdx +++ b/authentication/email.mdx @@ -179,16 +179,25 @@ const response = await client.emailAuth({ - + If you manage email flows with policies, update to the new activity types: - | Flow | Old Activities | New Activity | - |------|---------------|--------------| - | EMAIL_AUTH | `ACTIVITY_TYPE_EMAIL_AUTH`, `ACTIVITY_TYPE_EMAIL_AUTH_V2` | `ACTIVITY_TYPE_EMAIL_AUTH_V3` | - | INIT_OTP_AUTH | `ACTIVITY_TYPE_INIT_OTP_AUTH`, `ACTIVITY_TYPE_INIT_OTP_AUTH_V2` | `ACTIVITY_TYPE_INIT_OTP_AUTH_V3` | - | INIT_OTP | `ACTIVITY_TYPE_INIT_OTP` | `ACTIVITY_TYPE_INIT_OTP_V2` | - | INIT_USER_EMAIL_RECOVERY | `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY` | `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2` | - + **EMAIL_AUTH**
+ Old: `ACTIVITY_TYPE_EMAIL_AUTH`, `ACTIVITY_TYPE_EMAIL_AUTH_V2`
+ New: `ACTIVITY_TYPE_EMAIL_AUTH_V3` + + **INIT_OTP_AUTH**
+ Old: `ACTIVITY_TYPE_INIT_OTP_AUTH`, `ACTIVITY_TYPE_INIT_OTP_AUTH_V2`
+ New: `ACTIVITY_TYPE_INIT_OTP_AUTH_V3` + + **INIT_OTP**
+ Old: `ACTIVITY_TYPE_INIT_OTP`
+ New: `ACTIVITY_TYPE_INIT_OTP_V2` + + **INIT_USER_EMAIL_RECOVERY**
+ Old: `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY`
+ New: `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY_V2` +