SMS Authentication

​

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.

​

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