Init Generic OTP

Initiate a Generic OTP activity

POST

/

public

/

v1

/

submit

/

init_otp

Authorizations

API Key

X-Stamp

string

header

required

X-Stamp

string

header

required

X-Stamp-Webauthn

string

header

required

Body

type · enum<string> · required

Enum options: ACTIVITY_TYPE_INIT_OTP

timestampMs · string · required

Timestamp (in milliseconds) of the request, used to verify liveness of user requests.

organizationId · string · required

Unique identifier for a given Organization.

parameters · object · required

parameters field

Show details

parameters.otpType

string

required

Whether to send OTP via SMS or email. Possible values: OTP_TYPE_SMS, OTP_TYPE_EMAIL

parameters.contact

string

required

Email or phone number to send the OTP code to

parameters.otpLength

number

Optional length of the OTP code. Default = 9

parameters.emailCustomization · object

emailCustomization field

Show details

parameters.emailCustomization.appName

string

The name of the application.

parameters.emailCustomization.logoUrl

string

A URL pointing to a logo in PNG format. Note this logo will be resized to fit into 340px x 124px.

parameters.emailCustomization.magicLinkTemplate

string

A template for the URL to be used in a magic link button, e.g. https://dapp.xyz/%s. The auth bundle will be interpolated into the %s.

parameters.emailCustomization.templateVariables

string

JSON object containing key/value pairs to be used with custom templates.

parameters.emailCustomization.templateId

string

Unique identifier for a given Email Template. If not specified, the default is the most recent Email Template.

parameters.smsCustomization · object

smsCustomization field

Show details

parameters.smsCustomization.template

string

Template containing references to .OtpCode i.e Your OTP is {{.OtpCode}}

parameters.userIdentifier

string

Optional client-generated user identifier to enable per-user rate limiting for SMS auth. We recommend using a hash of the client-side IP address.

parameters.sendFromEmailAddress

string

Optional custom email address from which to send the OTP email

parameters.alphanumeric

boolean

Optional flag to specify if the OTP code should be alphanumeric (Crockford’s Base32). Default = true

parameters.sendFromEmailSenderName

string

Optional custom sender name for use with sendFromEmailAddress; if left empty, will default to ‘Notifications’

parameters.expirationSeconds

string

Expiration window (in seconds) indicating how long the OTP is valid for. If not provided, a default of 5 minutes will be used. Maximum value is 600 seconds (10 minutes)

parameters.replyToEmailAddress

string

Optional custom email address to use as reply-to

Response

A successful response returns the following fields:

activity · object · required

The activity object containing type, intent, and result

Show activity details

activity.type

string

required

The activity type

activity.intent

object

required

The intent of the activity

Show intent details

activity.intent.initOtpIntent

object

required

The initOtpIntent object

Show initOtpIntent details

activity.intent.initOtpIntent.otpType

string

required

Whether to send OTP via SMS or email. Possible values: OTP_TYPE_SMS, OTP_TYPE_EMAIL

activity.intent.initOtpIntent.contact

string

required

Email or phone number to send the OTP code to

activity.intent.initOtpIntent.otpLength

number

Optional length of the OTP code. Default = 9

activity.intent.initOtpIntent.emailCustomization

object

emailCustomization field

Show emailCustomization details

activity.intent.initOtpIntent.emailCustomization.appName

string

The name of the application.

activity.intent.initOtpIntent.emailCustomization.logoUrl

string

A URL pointing to a logo in PNG format. Note this logo will be resized to fit into 340px x 124px.

activity.intent.initOtpIntent.emailCustomization.magicLinkTemplate

string

A template for the URL to be used in a magic link button, e.g. https://dapp.xyz/%s. The auth bundle will be interpolated into the %s.

activity.intent.initOtpIntent.emailCustomization.templateVariables

string

JSON object containing key/value pairs to be used with custom templates.

activity.intent.initOtpIntent.emailCustomization.templateId

string

Unique identifier for a given Email Template. If not specified, the default is the most recent Email Template.

activity.intent.initOtpIntent.smsCustomization

object

smsCustomization field

Show smsCustomization details

activity.intent.initOtpIntent.smsCustomization.template

string

Template containing references to .OtpCode i.e Your OTP is {{.OtpCode}}

activity.intent.initOtpIntent.userIdentifier

string

Optional client-generated user identifier to enable per-user rate limiting for SMS auth. We recommend using a hash of the client-side IP address.

activity.intent.initOtpIntent.sendFromEmailAddress

string

Optional custom email address from which to send the OTP email

activity.intent.initOtpIntent.alphanumeric

boolean

Optional flag to specify if the OTP code should be alphanumeric (Crockford’s Base32). Default = true

activity.intent.initOtpIntent.sendFromEmailSenderName

string

Optional custom sender name for use with sendFromEmailAddress; if left empty, will default to ‘Notifications’

activity.intent.initOtpIntent.expirationSeconds

string

Expiration window (in seconds) indicating how long the OTP is valid for. If not provided, a default of 5 minutes will be used. Maximum value is 600 seconds (10 minutes)

activity.intent.initOtpIntent.replyToEmailAddress

string

Optional custom email address to use as reply-to

activity.result

object

required

The result of the activity

Show result details

activity.result.initOtpResult

object

required

The initOtpResult object

Show initOtpResult details

activity.result.initOtpResult.otpId

string

required

Unique identifier for an OTP authentication

cURL

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/init_otp \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <YOUR_API_KEY.YOUR_API_SECRET>" \
  --data '{
    "type": "ACTIVITY_TYPE_INIT_OTP",
    "timestampMs": "<string> (e.g. 1746736509954)",
    "organizationId": "<string> (Your Organization ID)",
    "parameters": {
        "otpType": "<string>",
        "contact": "<string>",
        "otpLength": 123,
        "emailCustomization": {
            "appName": "<string>",
            "logoUrl": "<string>",
            "magicLinkTemplate": "<string>",
            "templateVariables": "<string>",
            "templateId": "<string>"
        },
        "smsCustomization": {
            "template": "<string>"
        },
        "userIdentifier": "<string>",
        "sendFromEmailAddress": "<string>",
        "alphanumeric": true,
        "sendFromEmailSenderName": "<string>",
        "expirationSeconds": "<string>",
        "replyToEmailAddress": "<string>"
    }
}'

200

{
  "activity": {
    "id": "<activity-id>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_INIT_OTP",
    "organizationId": "<organization-id>",
    "timestampMs": "<timestamp> (e.g. 1746736509954)",
    "result": {
      "activity": {
        "type": "<string>",
        "intent": {
          "initOtpIntent": {
            "otpType": "<string>",
            "contact": "<string>",
            "otpLength": 123,
            "emailCustomization": {
              "appName": "<string>",
              "logoUrl": "<string>",
              "magicLinkTemplate": "<string>",
              "templateVariables": "<string>",
              "templateId": "<string>"
            },
            "smsCustomization": {
              "template": "<string>"
            },
            "userIdentifier": "<string>",
            "sendFromEmailAddress": "<string>",
            "alphanumeric": true,
            "sendFromEmailSenderName": "<string>",
            "expirationSeconds": "<string>",
            "replyToEmailAddress": "<string>"
          }
        },
        "result": {
          "initOtpResult": {
            "otpId": "<string>"
          }
        }
      }
    }
  }
}

Assistant

Responses are generated using AI and may contain mistakes.