Skip to main content

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 serverside based on the user's IP address or public key.

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.

note

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