Skip to content

6-digit to 9-digit #310

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

6-digit to 9-digit #310

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
ae9cc41
Documentation edits made through Mintlify web editor
mintlify[bot] May 15, 2025
4662db5
update docs for sms, email, remove movement
moe-dev May 15, 2025
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
55 changes: 18 additions & 37 deletions authentication/email.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebarTitle: "Email"

**One-Time Password**

- Uses a 6-digit one-time password sent via email
- Uses a 6-9 digit or bech32 alphanumeric one-time password sent via email
- Simple, and familiar user experience

**Credential Bundle**
Expand All @@ -26,7 +26,6 @@ Email Authentication is built with expiring API keys as the foundation. The two
The authentication process happens in two steps:

<Steps>
<Step>A 6-digit OTP code is sent to the user's verified email address</Step>
<Step>
Upon verification of the correct code, an API key credential is generated
and encrypted for the client
Expand All @@ -51,21 +50,20 @@ The flow begins with a new activity of type `ACTIVITY_TYPE_INIT_OTP_AUTH` with t
- `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

After receiving the 6-digit code, users complete authentication with `ACTIVITY_TYPE_OTP_AUTH`:
After receiving the OTP code, users complete authentication with `ACTIVITY_TYPE_OTP_AUTH`:

- `otpId`: ID from the init activity
- `otpCode`: the 6-digit code received via email
- `otpCode`: the 6-9 digit or bech32 alphanumeric code received via email
- `targetPublicKey`: public key for credential encryption
- `apiKeyName`: optional name (defaults to `OTP Auth - <Timestamp>`)
- `expirationSeconds`: optional validity window (defaults to 15 minutes)
- `invalidateExisting`: optional boolean to invalidate previous OTP Auth API keys

<Frame>
<img
src="/images/authentication/img/auth_otp_email.png"
alt="auth otp email"
/>
![auth otp email](/images/authentication/img/auth_otp_email.png)
</Frame>

### OTP Rate Limits
Expand All @@ -88,7 +86,7 @@ This alternative method uses `ACTIVITY_TYPE_EMAIL_AUTH` with these parameters:
- `invalidateExisting`: optional boolean to invalidate previous Email Auth API keys

<Frame>
<img src="/images/authentication/img/auth_email.png" alt="auth email" />
![auth email](/images/authentication/img/auth_email.png)
</Frame>

### Recovery Flow
Expand All @@ -104,7 +102,7 @@ The recovery process consists of two phases:
2. **Finalization**: User decrypts the recovery credential and uses it to sign an `ACTIVITY_TYPE_RECOVER_USER` activity, which can add new authenticators to regain account access

<Frame>
<img src="/images/authentication/img/auth_email.png" alt="auth email" />
![auth email](/images/authentication/img/auth_email.png)
</Frame>

## Authorization
Expand All @@ -127,24 +125,18 @@ Specifically:
### Recovery

- `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY`:

- Initiates the recovery process
- Requires proper authorization via policies
- Can target any user in the organization or sub-organizations

- `ACTIVITY_TYPE_RECOVER_USER`:

- Must be signed by the recovery credential received via email
- Users can add credentials to their own user when authenticated
- Recovery credentials expire after 15 minutes
- Only the most recent recovery credential remains valid
- Users can add new authenticators to regain account access when authenticated with a recovery credential

<Frame>
<img
src="/images/authentication/img/diagrams/email_auth_authorization.png"
alt="email auth authorization"
/>
![email auth authorization](/images/authentication/img/diagrams/email_auth_authorization.png)
</Frame>

## Implementation in Sub-organizations
Expand All @@ -160,33 +152,23 @@ Both authentication methods and recovery work seamlessly with [sub-organizations

For implementation details:

<CardGroup>
<Card
title="Sub-Organization Email Auth Guide"
href="/embedded-wallets/sub-organization-auth"
icon="file-lines"
iconType="solid"
horizontal
/>
<Card
title="Sub-Organization Recovery Guide"
href="/embedded-wallets/sub-organization-recovery"
icon="file-lines"
iconType="solid"
horizontal
/>
<CardGroup cols={2}>
<Card title="Sub-Organization Email Auth Guide" icon="file-lines" iconType="solid" horizontal href="/embedded-wallets/sub-organization-auth">

</Card>
<Card title="Sub-Organization Recovery Guide" icon="file-lines" iconType="solid" horizontal href="/embedded-wallets/sub-organization-recovery">

</Card>
</CardGroup>

## Implementation in Organizations

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
- Recovery features if needed

2. Users initiating the request must have appropriate permissions

## Opting Out
Expand All @@ -205,10 +187,9 @@ When creating sub-organizations, use:
- `disableEmailAuth` parameter for credential bundle authentication
- `disableEmailRecovery` parameter for recovery

## Implementation Notes[​](#implementation-notes "Direct link to Implementation Notes")
## Implementation Notes[​](#implementation-notes)

- Users are limited to:

- 10 long-lived API keys
- 10 expiring API keys (oldest are discarded when limit is reached)

Expand Down Expand Up @@ -246,4 +227,4 @@ turnkey request --host api.turnkey.com --path /public/v1/submit/set_organization
"name": "FEATURE_NAME_EMAIL_AUTH"
}
}' --organization <YOUR-ORG-ID>
```
```
20 changes: 14 additions & 6 deletions authentication/sms.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,23 @@
---
title: "SMS Authentication"
description: "SMS authentication enables users to authenticate their Turnkey account using their phone number via a 6-digit one-time password (OTP). When authenticated, users receive an expiring API key stored in memory within an iframe, which functions like a session key to access their wallet."
description: "SMS authentication enables users to authenticate their Turnkey account using their phone number via a 6-9 digit or bech32 alphanumeric one-time password (OTP). When authenticated, users receive an expiring API key stored in memory within an iframe, which functions like a session key to access their wallet."
sidebarTitle: "SMS"
---

## Access and Pricing

SMS authentication is available to all Enterprise customers. To enable this feature, please reach out to the Turnkey team.

SMS pricing is usage-based and varies depending on the country of the destination phone number. A downloadable price list for all supported countries is available <a href="https://tkhq-prod-public-content.s3.us-east-1.amazonaws.com/sms-prices.csv" download>here as a CSV</a>.
SMS pricing is usage-based and varies depending on the country of the destination phone number. A downloadable price list for all supported countries is available <a href="https://tkhq-prod-public-content.s3.us-east-1.amazonaws.com/sms-prices.csv">
here as a CSV</a>

.

## How It Works

SMS authentication uses two activities:

1. `INIT_OTP_AUTH` - sends a 6-digit OTP code to the specified phone number
1. `INIT_OTP_AUTH` - sends a 6-9 digit or bech32 alphanumeric OTP code to the specified phone number
2. `OTP_AUTH` - verifies the code and returns an encrypted API key credential

## Implementation
Expand All @@ -28,13 +31,16 @@ To start SMS authentication, create an activity with `ACTIVITY_TYPE_INIT_OTP_AUT
- `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.
- `smsCustomizationParams`: optional parameters for customizing sms.
- `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

### Verifying the OTP

Once the user receives their code, use `ACTIVITY_TYPE_OTP_AUTH` with these parameters:

- `otpId`: ID from the `INIT_OTP_AUTH` response
- `otpCode`: the 6-digit code received via SMS
- `otpCode`: the 6-9 digit or bech32 alphanumeric code received via SMS
- `targetPublicKey`: public key for credential encryption
- `apiKeyName`: optional name for the API Key (defaults to `OTP Auth - <Timestamp>`)
- `expirationSeconds`: optional duration in seconds (defaults to 15 minutes)
Expand All @@ -44,7 +50,9 @@ Once the user receives their code, use `ACTIVITY_TYPE_OTP_AUTH` with these param

SMS authentication requires proper permissions through policies or parent organization status.

<Info>Non-paying accounts are limited to **50 SMS messages** per month.</Info>
<Info>
Non-paying accounts are limited to **50 SMS messages** per month.
</Info>

## Enabling/Disabling SMS Auth

Expand Down Expand Up @@ -80,4 +88,4 @@ In order to safeguard users, Turnkey enforces rate limits for OTP auth activitie

- 3 requests per 3 minutes per unique `userIdentifier`
- 3 retries max per code, after which point that code will be locked
- 3 active codes per user, each with a 5 minute TTL
- 3 active codes per user, each with a 5 minute TTL
12 changes: 6 additions & 6 deletions networks/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,12 @@ Our SDK provides tools and scripts to help in constructing and signing basic tra

At our highest level of support, Turnkey offers the ability to parse transactions and define custom policies based on transaction parameters.

| Tier | Depth of support | EVM | SVM | BTC | ATOM | TRON | SUI | APT | TON | XRP | SEI |
| ------ | :------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
| Tier 1 | Curve-level | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
| Tier 2 | Address derivation | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
| Tier 3 | SDK construction and signing | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | | | | | | | | |
| Tier 4 | Transaction parsing and policies | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | | | <Icon icon="square-check" iconType="solid" /> | | | | | |
| Tier | Depth of support | EVM | SVM | BTC | ATOM | TRON | SUI | APT | MOVE | TON | XRP | SEI | FLARE |
| ------ | :------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | ----- |
| Tier 1 | Curve-level | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
| Tier 2 | Address derivation | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | |
| Tier 3 | SDK construction and signing | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | | | | | | | | | | |
| Tier 4 | Transaction parsing and policies | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | | | | | | | | | | |

For more details about each ecosystem, refer to the pages below:

Expand Down
2 changes: 1 addition & 1 deletion security/reporting-a-vulnerability.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "Turnkey highly values the security of our software, services, and
mode: "wide"
---

If you believe you have found very serious vulnerability, we ask that you encrypt the message to the `security.turnkey.com` PGP key (FP: `AD6C 3E61 17A5 886E 550E F8BB 3ACD E5EA 8DC7 9275`). This can also be found on Turnkey's website at https://www.turnkey.com/.well-known/security.asc.txt
If you believe you have found a very serious vulnerability, we ask that you encrypt the message to the [security@turnkey.com](mailto:security@turnkey.com) PGP public key (fingerprint: `AD6C 3E61 17A5 886E 550E F8BB 3ACD E5EA 8DC7 9275`). You can find this key at https://www.turnkey.com/.well-known/security.asc

Upon receiving a report, our team promptly assesses and prioritizes the vulnerability based on its severity and potential impact. We then take reasonable and appropriate steps to mitigate and remediate the identified risks in accordance with our internal policies and timelines. Where feasible, we will endeavor to keep the reporter informed throughout the process. Our approach is designed to ensure confidentiality and offer safe harbor to researchers, promising that those who report vulnerabilities ethically and in good faith will not face legal action.

Expand Down