Init OTP auth - Turnkey

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/init_otp_auth \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <YOUR_API_KEY.YOUR_API_SECRET>" \
  --data '{
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "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>",
        "replyToEmailAddress": "<string>"
    }
}'

{
  "activity": {
    "id": "<activity-id>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "organizationId": "<organization-id>",
    "timestampMs": "<timestamp> (e.g. 1746736509954)",
    "result": {
      "activity": {
        "type": "<string>",
        "intent": {
          "initOtpAuthIntentV2": {
            "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>",
            "replyToEmailAddress": "<string>"
          }
        },
        "result": {
          "initOtpAuthResultV2": {
            "otpId": "<string>"
          }
        }
      }
    }
  }
}

POST

public

submit

init_otp_auth

Authorizations

X-Stamp

string

header

required

Body

type

enum<string>

required

Enum options: ACTIVITY_TYPE_INIT_OTP_AUTH_V2

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

Enum to specifiy whether to send OTP via SMS or 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.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.initOtpAuthIntentV2

object

required

The initOtpAuthIntentV2 object

Show initOtpAuthIntentV2 details

activity.intent.initOtpAuthIntentV2.otpType

string

required

Enum to specifiy whether to send OTP via SMS or email

activity.intent.initOtpAuthIntentV2.contact

string

required

Email or phone number to send the OTP code to

activity.intent.initOtpAuthIntentV2.otpLength

number

Optional length of the OTP code. Default = 9

activity.intent.initOtpAuthIntentV2.emailCustomization

object

emailCustomization field

Show emailCustomization details

activity.intent.initOtpAuthIntentV2.emailCustomization.appName

string

The name of the application.

activity.intent.initOtpAuthIntentV2.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.initOtpAuthIntentV2.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.initOtpAuthIntentV2.emailCustomization.templateVariables

string

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

activity.intent.initOtpAuthIntentV2.emailCustomization.templateId

string

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

activity.intent.initOtpAuthIntentV2.smsCustomization

object

smsCustomization field

Show smsCustomization details

activity.intent.initOtpAuthIntentV2.smsCustomization.template

string

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

activity.intent.initOtpAuthIntentV2.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.initOtpAuthIntentV2.sendFromEmailAddress

string

Optional custom email address from which to send the OTP email

activity.intent.initOtpAuthIntentV2.alphanumeric

boolean

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

activity.intent.initOtpAuthIntentV2.sendFromEmailSenderName

string

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

activity.intent.initOtpAuthIntentV2.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.initOtpAuthResultV2

object

required

The initOtpAuthResultV2 object

Show initOtpAuthResultV2 details

activity.result.initOtpAuthResultV2.otpId

string

required

Unique identifier for an OTP authentication

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/init_otp_auth \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <YOUR_API_KEY.YOUR_API_SECRET>" \
  --data '{
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "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>",
        "replyToEmailAddress": "<string>"
    }
}'

{
  "activity": {
    "id": "<activity-id>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "organizationId": "<organization-id>",
    "timestampMs": "<timestamp> (e.g. 1746736509954)",
    "result": {
      "activity": {
        "type": "<string>",
        "intent": {
          "initOtpAuthIntentV2": {
            "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>",
            "replyToEmailAddress": "<string>"
          }
        },
        "result": {
          "initOtpAuthResultV2": {
            "otpId": "<string>"
          }
        }
      }
    }
  }
}

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/init_otp_auth \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <YOUR_API_KEY.YOUR_API_SECRET>" \
  --data '{
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "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>",
        "replyToEmailAddress": "<string>"
    }
}'

{
  "activity": {
    "id": "<activity-id>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "organizationId": "<organization-id>",
    "timestampMs": "<timestamp> (e.g. 1746736509954)",
    "result": {
      "activity": {
        "type": "<string>",
        "intent": {
          "initOtpAuthIntentV2": {
            "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>",
            "replyToEmailAddress": "<string>"
          }
        },
        "result": {
          "initOtpAuthResultV2": {
            "otpId": "<string>"
          }
        }
      }
    }
  }
}

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/init_otp_auth \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <YOUR_API_KEY.YOUR_API_SECRET>" \
  --data '{
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "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>",
        "replyToEmailAddress": "<string>"
    }
}'

{
  "activity": {
    "id": "<activity-id>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "organizationId": "<organization-id>",
    "timestampMs": "<timestamp> (e.g. 1746736509954)",
    "result": {
      "activity": {
        "type": "<string>",
        "intent": {
          "initOtpAuthIntentV2": {
            "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>",
            "replyToEmailAddress": "<string>"
          }
        },
        "result": {
          "initOtpAuthResultV2": {
            "otpId": "<string>"
          }
        }
      }
    }
  }
}

POST

public

submit

init_otp_auth

Authorizations

X-Stamp

string

header

required

Body

type

enum<string>

required

Enum options: ACTIVITY_TYPE_INIT_OTP_AUTH_V2

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

Enum to specifiy whether to send OTP via SMS or 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.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.initOtpAuthIntentV2

object

required

The initOtpAuthIntentV2 object

Show initOtpAuthIntentV2 details

activity.intent.initOtpAuthIntentV2.otpType

string

required

Enum to specifiy whether to send OTP via SMS or email

activity.intent.initOtpAuthIntentV2.contact

string

required

Email or phone number to send the OTP code to

activity.intent.initOtpAuthIntentV2.otpLength

number

Optional length of the OTP code. Default = 9

activity.intent.initOtpAuthIntentV2.emailCustomization

object

emailCustomization field

Show emailCustomization details

activity.intent.initOtpAuthIntentV2.emailCustomization.appName

string

The name of the application.

activity.intent.initOtpAuthIntentV2.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.initOtpAuthIntentV2.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.initOtpAuthIntentV2.emailCustomization.templateVariables

string

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

activity.intent.initOtpAuthIntentV2.emailCustomization.templateId

string

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

activity.intent.initOtpAuthIntentV2.smsCustomization

object

smsCustomization field

Show smsCustomization details

activity.intent.initOtpAuthIntentV2.smsCustomization.template

string

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

activity.intent.initOtpAuthIntentV2.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.initOtpAuthIntentV2.sendFromEmailAddress

string

Optional custom email address from which to send the OTP email

activity.intent.initOtpAuthIntentV2.alphanumeric

boolean

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

activity.intent.initOtpAuthIntentV2.sendFromEmailSenderName

string

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

activity.intent.initOtpAuthIntentV2.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.initOtpAuthResultV2

object

required

The initOtpAuthResultV2 object

Show initOtpAuthResultV2 details

activity.result.initOtpAuthResultV2.otpId

string

required

Unique identifier for an OTP authentication

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/init_otp_auth \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <YOUR_API_KEY.YOUR_API_SECRET>" \
  --data '{
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "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>",
        "replyToEmailAddress": "<string>"
    }
}'

{
  "activity": {
    "id": "<activity-id>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "organizationId": "<organization-id>",
    "timestampMs": "<timestamp> (e.g. 1746736509954)",
    "result": {
      "activity": {
        "type": "<string>",
        "intent": {
          "initOtpAuthIntentV2": {
            "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>",
            "replyToEmailAddress": "<string>"
          }
        },
        "result": {
          "initOtpAuthResultV2": {
            "otpId": "<string>"
          }
        }
      }
    }
  }
}

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/init_otp_auth \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <YOUR_API_KEY.YOUR_API_SECRET>" \
  --data '{
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "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>",
        "replyToEmailAddress": "<string>"
    }
}'

{
  "activity": {
    "id": "<activity-id>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_INIT_OTP_AUTH_V2",
    "organizationId": "<organization-id>",
    "timestampMs": "<timestamp> (e.g. 1746736509954)",
    "result": {
      "activity": {
        "type": "<string>",
        "intent": {
          "initOtpAuthIntentV2": {
            "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>",
            "replyToEmailAddress": "<string>"
          }
        },
        "result": {
          "initOtpAuthResultV2": {
            "otpId": "<string>"
          }
        }
      }
    }
  }
}

Authorizations

Body

Response

Changelogs

Authorizations

Body

Response