Skip to main content
POST
/
challenge
Initiate challenge
curl --request POST \
  --url https://api.authsignal.com/v1/challenge \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "verificationMethod": "SMS",
  "action": "signInWithSms",
  "phoneNumber": "+64270000000",
  "locale": "en"
}
'
{
  "challengeId": "<string>",
  "idempotencyKey": "<string>",
  "expiresAt": 123
}

Authorizations

​
Authorization
string
header
required

Use your Authsignal secret key as the username and leave the password empty. The secret key can be found in the API Keys section of the Authsignal Portal settings page.

Body

application/json
​
verificationMethod
enum<string>
required

The verification method to use for the challenge.

Available options:
EMAIL_OTP,
SMS,
WHATSAPP
​
action
string
required

The action code used to identify the challenge in the Authsignal Portal.

​
idempotencyKey
string

The idempotency key for the action. An idempotency key can be used to initiate multiple challenges for the same action.

​
phoneNumber
string

The phone number in E.164 format. Required if the verification method is 'SMS'.

​
email
string

The email address. Required if the verification method is 'EMAIL_OTP'.

​
userId
string

The primary ID of the user in your system. Required when initiating a challenge to enroll or update an authenticator for an existing user.

​
scope
enum<string>

Providing scopes will authorize enrolling or updating an authenticator for an existing user. Must only be provided when initiating a challenge from an already authenticated state.

Available options:
add:authenticators,
update:authenticators,
add:authenticators update:authenticators
​
locale
string

The user's locale in BCP 47 format. Used to localize email and SMS messages.

Example:

"en"

​
ipAddress
string

The user's IP address. Can be provided to use rules based on location or other IP-derived features.

​
userAgent
string

The user agent identifying a browser or app. Can be provided to use rules based on device.

​
deviceId
string

An ID which identifies the user's device. Can be provided to use rules based on device.

​
custom
object

A JSON object which can include any key/value pairs. Can be provided to use rules based on your own data points.

Response

OK

​
challengeId
string
required

The ID of the challenge.

​
idempotencyKey
string
required

The idempotency key for the action. An idempotency key can be used to initiate multiple challenges for the same action.

​
expiresAt
number
required

The challenge expiry as a Unix timestamp in seconds.