Skip to content

Start an Authentication

post
https://api.reach.talkylabs.com/rest/authentix/v1/configurations/{configurationId}/authentications

This operation allows to start a new authentication process by sending a code via a specific channel.

Parameters

  • configurationIdstringrequiredpath

    The identifier of the configuration being used.

  • deststringrequired

    The phone number or email where to send the authentication code. Phone numbers must be in E.164 format.

  • channelstringrequired

    The channel by which the authentication code is sent. It can be one of sms, or email.

  • serviceNamestringoptional

    A service name overwriting the one defined in the configuration.

  • customCodestringoptional

    The pre-generated code to be sent. Its length should be between 4 and 10 inclusive.

  • paymentInfostringoptional

    Information related to the digital payment to authenticate. It is required when usedForDigitalPayment is true. It is ignored otherwise. It is a stringfied JSON map where keys are payee, amount, and currency and the associated values are respectively the payee, the amount, and the currency of a financial transaction. For example "{'payee': 'ACME', 'amount': '1000', 'currency': 'xaf'}".

  • templateIdstringoptional

    This is the ID of the message template to use for sending the authenetication code. It could be an sms or email template depending on the channel being used. It overwirites the template ID defined in the configuration if any.

  • templateDataMapstringoptional

    A stringfied JSON map where keys are message template parameters and the values are the parameter values to be used when sending the authentication code. It may also be used to provide additional parameters for sending email based authentications such as the email used for sending the code. For example "{'sender_email': 'me@my-company.com'}".

Example 1: Initiate a Authentication with SMS

The example below demonstrates how to inititate a authentication with SMS using the Reach Authentix API.

curl -X POST https://api.reach.talkylabs.com/rest/authentix/v1/configurations/CIDXXXXXXXXXXXX/authentications --data-urlencode "dest=+237671234567" --data-urlencode "channel=sms" -H "ApiUser: $REACH_TALKYLABS_API_USER" -H "ApiKey: $REACH_TALKYLABS_API_KEY"
Output example
{
  "appletId": "AIDXXXXXXXXXXXX",
  "apiVersion": "1.0.0",
  "configurationId": "CIDXXXXXXXXXXXX",
  "authenticationId": "VIDXXXXXXXXXXXX",
  "status": "awaiting",
  "dest": "+237671234567",
  "channel": "sms",
  "expiryTime": 5,
  "maxTrials": 5,
  "maxControls": 3,
  "paymentInfo": {
    "payee": "ACME",
    "amount": 1000,
    "currency": "xaf"
  },
  "trials": [
    {
      "dateCreated": "2016-08-29T09:12:33.001Z",
      "trialId": "TRDXXXXXXXXXX",
      "channel": "sms"
    }
  ],
  "dateCreated": "2016-08-29T09:12:33.001Z",
  "dateUpdated": "2016-08-29T09:12:35.001Z"
}

Example 2: Initiate a Authentication with Email

The example below demonstrates how to inititate a authentication with Email using the Reach Authentix API. This assumes SMTP settings were defined in the configuration being used.

curl -X POST https://api.reach.talkylabs.com/rest/authentix/v1/configurations/CIDXXXXXXXXXXXX/authentications --data-urlencode "dest=user@customsite.com" --data-urlencode "channel=email" -H "ApiUser: $REACH_TALKYLABS_API_USER" -H "ApiKey: $REACH_TALKYLABS_API_KEY"
Output example
{
  "appletId": "AIDXXXXXXXXXXXX",
  "apiVersion": "1.0.0",
  "configurationId": "CIDXXXXXXXXXXXX",
  "authenticationId": "VIDXXXXXXXXXXXX",
  "status": "awaiting",
  "dest": "+237671234567",
  "channel": "sms",
  "expiryTime": 5,
  "maxTrials": 5,
  "maxControls": 3,
  "paymentInfo": {
    "payee": "ACME",
    "amount": 1000,
    "currency": "xaf"
  },
  "trials": [
    {
      "dateCreated": "2016-08-29T09:12:33.001Z",
      "trialId": "TRDXXXXXXXXXX",
      "channel": "sms"
    }
  ],
  "dateCreated": "2016-08-29T09:12:33.001Z",
  "dateUpdated": "2016-08-29T09:12:35.001Z"
}