Overview #

The CAMARA One Time Password (OTP) SMS API is designed to dispatch transient OTPs via SMS to a specified phone number and subsequently validate them, serving as evidence of the possession of the said number.

The complete definition of the CAMARA API can be found on: https://github.com/camaraproject/OTPvalidationAPI

Introduction #

This API conducts instantaneous validations to confirm that the user is in possession of the device associated with the given mobile number. It is a prevalent mode of affirming device possession by transmitting an OTP via SMS and subsequently authenticating it.

SMS OTPs serve as secure gateways for one-time access or single transactions, proving more secure and appropriate than user-generated passwords for singular transactions. The recipient employs this unique code as an augmented security layer to access services, websites, or apps.

Quick Start #

API Service Endpoint #

The API has two defined endpoints:

• POST /one-time-password-sms/v0/send-code: Dispatches an SMS containing the OTP code and the intended message to the specified phone number.
  Demo Server: https://auth.aloaha.com/one-time-password-sms/v0/send-code
• POST /one-time-password-sms/v0/validate-code: Validates the received code against the provided authenticationId.
  Demo Server: https://auth.aloaha.com/one-time-password-sms/v0/validate-code

Authentication #

A security access token, based on two-legged authentication with a dedicated scope, is mandatory for utilizing this API. Such token can be requested with the Web Services API: MobileToken

Authentication and Authorization #

The API employs OAUTH 2.0 client credentials grant, suitable for server-to-server interactions involving trusted partners or clients, with no protected user data involved.

API Documentation #

Details #

Endpoint Definition #

The API exposes the following REST-based endpoints for OTP SMS operations:

• POST /one-time-password-sms/v0/send-code: Initiates a request to send an OTP code to a mobile phone number.
• POST /one-time-password-sms/v0/validate-code: Initiates a request to validate an OTP code for the provided authenticationId.

Request Code #

• HTTP Request: POST /one-time-password-sms/v0/send-code
• Request Body Parameters:
• phoneNumber: User’s phone number in ‘E164 with +’ format.
• message: Message template for composing the SMS content. It must incorporate the label {{code}} to include the short code.
• requestpin: Introduced by CodeB to avoid any artificial traffic inflation (Hello Elon)

Validate Code #

• HTTP Request: POST /one-time-password-sms/v0/validate-code
• Request Body Parameters:
• authenticationId: Unique id of the verification attempt.
• code: Temporary, short code to be validated.

Code Snippets #

The snippets illustrate REST-based API calls using “curl” to request. The credentials for API authentication should be configured based on the target security system.

# Request code
curl -X 'POST' <base-url>/one-time-password-sms/v0/send-code
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer <token>"
-d '{ "phoneNumber": "+35679567034", "message": "{{code}} is your short code to authenticate with CodeB via SMS", "requestpin": "569766"}'

Result: {"authenticationId":"b96f93c9ea0443358745eb2d244e1eea"}
Web Services Wrapper: https://auth.codeb.io/ws/camara.asmx?op=send_code

# Validate code
curl -X 'POST' <base-url>/one-time-password-sms/v0/validate-code
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer <token>"
-d '{ "authenticationId": "3a29c4e293054c759fe80bc7ee77db96", "code": "649493"}'

Result: HTTP/1.1 204 OK
Web Services Wrapper: https://auth.codeb.io/ws/camara.asmx?op=validate_code