​
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. Select your country below to view pricing.
Select Your Country To View Pricing
Cost
0.000¢
Albania
Andorra
Angola
Argentina
Armenia
Australia
Austria
Azerbaijan
Bahamas
Bahrain
Bangladesh
Barbados
Belgium
Belize
Benin
Bolivia
Bosnia And Herzegovina
Botswana
Brazil
British Virgin Islands
Brunei
Cameroon
Cape Verde
Cayman Islands
Chad
Chile
Colombia
Costa Rica
Croatia
Curacao
Cyprus
Czechia
Democratic Republic Of The Congo
Denmark
Djibouti
Dominica
Ecuador
El Salvador
Equatorial Guinea
Estonia
Faroe Islands
Fiji
Finland
France
French Polynesia
Gambia
Georgia
Germany
Ghana
Gibraltar
Greece
Grenada
Guadelupe
Guatemala
Guinea
Guyana
Haiti
Honduras
Hong Kong
Hungary
Iceland
India
Indonesia
Ireland
Israel
Italy
Ivory Coast
Jamaica
Japan
Kosovo
Kuwait
Kyrgyzstan
Laos
Latvia
Lebanon
Lesotho
Liberia
Lithuania
Luxembourg
Madagascar
Malaysia
Maldives
Mali
Malta
Mauritius
Mexico
Moldova
Mongolia
Montenegro
Morocco
Mozambique
Namibia
Nepal
Netherlands
New Zealand
Nicaragua
Niger
Nigeria
Norway
Pakistan
Panama
Peru
Philippines
Poland
Portugal
Puerto Rico 1
Puerto Rico 2
Qatar
Reunion
Romania
Saint Lucia
Saint Vincent And Grenadines
Samoa
Saudi Arabia
Senegal
Serbia
Seychelles
Sierra Leone
Singapore
Slovenia
South Africa
South Korea
Spain
Suriname
Swaziland
Sweden
Switzerland
Tajikistan
Tanzania
Thailand
Togo
Trinidad And Tobago
Tunisia
United States
Uruguay
Uzbekistan
Venezuela

​
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