Authentication - Akedly API Reference

1- 🔒 Requesting an authentication transaction

Once you’ve set-up your pipeline, it’s now time to request an authentication request for when your user to asking to be authenticated.

📝 Request Parameters & API Call

If you decide to use the email variable in the verificationAddress, make sure you’ve added the E-mail as a verification method inside the pipeline options after creating it on the web-app https://app.akedly.io/pipline/${pipelineID}

Name
APIKey
Type
string
Description
The API key you’ve copied from the API section of the Akedly web-app
Name
pipelineID
Type
string
Description
The id of the pipeline you’ve created, you can copy it from the basic details of the pipeline
Name
verificationAddress
Type
JSON
Description
a JSON object containing the phoneNumber and email of the end user to be verified (will receive the OTP on) with the country code attached to it. Here is a link for reference regarding all countries https://countrycode.org/
Name
pipelineID
Type
string
Description
The id of the pipeline you’ve created, you can copy it from the basic details of the pipeline

Result of the request should be as following:

Name
status
Type
string
Description
a string of the status of your transaction request
Name
data
Type
JSON
Description
JSON object containing transactionID This is the sole reason why we’ve made this request. This is your request key and permission given to you by our server to authenticate your user. You shall take this transactionID and activate it using the next API to send the OTP to your user.
Name
message
Type
string
Description
a string of the status of your transaction request

It’s recommended to create an SQL table or a Collection in your own database to tie the operation you’re currently doing for your users with the transactionID generated so it would be easier to retrieve the data you were handling for your user after they are redirected again to your front-end URL.
For example ; if you’re using the authentication step to redirect the user to a successful registration, you may want to save the transactionID alongside the id of the registered user in order to mark them as verified after they’ve been redirected from Akedly to your front-end URL

Request Body & URL

POST

https://api.akedly.io/api/v1/transactions

{
  "APIKey": "6e1d6585bbe17f6abc80cf10a1********ad3fe197775b19fde2ebb5464d",
  "pipelineID": "6748*******f948b29ef",
  "verificationAddress": {
    "phoneNumber": "+20155****2491",
    "email": "testmail@akedly.io"
  }
}

Response

JSON

201 Status

{
  "status": "success",
  "data": {
    "transactionID": "a77549536888557729a0e4cd454d28371f658426135af11ce6cba7f6123aafff"
  },
  "message": "Main transaction created successfully"
}

2- 📩 Activating the auth transaction & sending the OTP

Once you’re received a transactionID, we will use it to send the OTP to the verificationAddress used inside the transaction in the previous API.

Request Body & URL

POST

https://api.akedly.io/api/v1/transactions/activate/{transactionID}

{
  //empty body
}

Result of the request should be similar to the following :

Upon successful response, the OTP has been sent to the user according to his verificationAddress json

If the verificationAddress contains both email and phoneNumber, the OTP will be sent on two different channels
- E-mail (always)
- User’s phone, which could be through one or more of the following channels :
  - WhatsApp if the number has WhatsApp
  - Local SMS Provider if the number doesn’t have WhatsApp and is a local Egyptian number
  - International SMS provider if the number doesn’t have WhatsApp and is not a local Egyptian number
This guarantees the arrival of the OTP to your user, which guarantees a very high chance of successful authentication. Only upon successful authentication we subtract your available quota, no matter how many messages or how many channels were used during the authentication process.

The data is an object called transactionReq which contains an _id attribute.

This _id will be used in the next step, so keep it at hand.

At this point, you should show the input GUI that you’ve created for your users. And you should be ready to receive their OTP input to send it back to us for verification.

Response

JSON

201 Status

{
	status : "success",
	message : "OTP sent successfully",
	emailSuccess : true,   //email sending status
	WhatsAppSuccess: true, //whatsapp sending status
    smsSuccess: true,      //sms sending status
	data : {
			_id : "66726b726cdd6713",
			.....
			.......
	}
}

Make sure you catch any 403 errors from this request’s response since if the OTP fails to send, you will receive an error that says so.

3- 🔐 Sending the user’s OTP input back to Akedly for verification

You should send the user’s input OTP to the following URL

Name
otp
Type
string
Description
The OTP input by the user. Make sure it’s a string.

If the user authenticated successfully - You should see the following response

Name
status
Type
string
Description
a string of the status of your transaction request
Name
data
Type
JSON
Description
JSON object containing mainTransaction and transactionReq objects.
Name
message
Type
string
Description
a string of the status of your transaction request
Name
mainTransaction
Type
JSON
Description
The mainTransaction is main transaction object you’ve received in step#1
Name
transactionReq
Type
JSON
Description
The transactionReq is the action initiated by your user to input the OTP and contains statistic about the exact time of verification, exact time of sending the OTP and their own input.

Please note that the data received here in the response is purely for logging purposes in case you’d like to store them in your own database using your own backend. You can already access the data through https://app.akedly.io/admin/verifications after logging onto your account.

If the user did not authenticate successfully - You will see the following response

Name
status
Type
number
Description
a number of the status of your transaction request
Name
data
Type
JSON
Description
JSON object containing frontendCallbackURL which is the URL you’ve provided in the pipeline options to redirect the user to in case of failure. (only used in case you are using the Akedly hosted frontend)
Name
message
Type
string
Description
a string of the status of your transaction request

If any other errors occur, you will also receive the above layout of the error with the message replaced by the explanatory message of the error from our servers.

Request Body & URL

POST

https://api.akedly.io/api/v1/transactions/verify/{_id}

{
  "otp": "123456"
}

Response

JSON

Success Response

{
  "message": "OTP verified successfully",
  "status": "success",
  "data": {
    "mainTransaction",
    "transactionReq"
  }
}

Response

JSON

Failure Response

{
  "message": "Invalid OTP",
  "status": 403,
  "data": {
    "frontendCallbackURL"
  }
}