SMS Authentication

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.

How It Works

SMS authentication uses two activities:

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

Implementation

Initiating SMS Authentication

To start SMS authentication, create an activity with ACTIVITY_TYPE_INIT_OTP_AUTH and the following parameters:

• otpType: must be set to "OTP_TYPE_SMS"
• contact: user’s phone number (must be previously approved and attached to the user’s organization data)
• 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 section below for more details.

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
• 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)
• invalidateExisting: optional boolean to invalidate previous OTP Auth API keys

Authorization

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

Non-paying accounts are limited to 50 SMS messages per month.

Enabling/Disabling SMS Auth

For Top-level Organizations

SMS authentication is disabled by default. Enable it using ACTIVITY_TYPE_SET_ORGANIZATION_FEATURE:

turnkey request --host api.turnkey.com --path /public/v1/submit/set_organization_feature --body '{
        "timestampMs": "'"$(date +%s)"'000",
        "type": "ACTIVITY_TYPE_SET_ORGANIZATION_FEATURE",
        "organizationId": "<YOUR-ORG-ID>",
        "parameters": {
                "name": "FEATURE_NAME_SMS_AUTH"
        }
}' --organization <YOUR-ORG-ID>

For Sub-organizations

• SMS auth is enabled by default
• Disable during creation using disableSmsAuth: true in the CreateSubOrganizationIntentV7 activity
• Disable after creation using ACTIVITY_TYPE_REMOVE_ORGANIZATION_FEATURE with feature name FEATURE_NAME_SMS_AUTH

Implementation Notes

• Users are limited to 10 long-lived API keys and 10 expiring API keys
• When the expiring API key limit is reached, the oldest key is automatically discarded

OTP Rate Limits

In order to safeguard users, Turnkey enforces rate limits for OTP auth activities. If a userIdentifier parameter is provided, the following limits are enforced:

• 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

Assistant

Responses are generated using AI and may contain mistakes.