Using PhenixID HTTP API to get OTP based on called-in phone number

Overview

The use case behind this API call:

- The end user will retreive one-time-password by calling to a specific phone number (company phone system)

- The company phone system will pick up the phone number of the called-in user

- The company phone system will call out to this api, sending in the phone number of the called-in user

- PhenixID MFA server will search for the user (based on the received phone number)

- If the user is found, an OTP will be generated and bound to the userID

- The PhenixID HTTP API will return the OTP value to the calling API client (the company phone system)

- The company phone system will automatically echo the one-time-password to the end user.

- API function end

 

After the api call:

- The end user will enter username, password and OTP (the service protected may vary) and click Login

- Username, password and OTP will be sent to PhenixID MFA server

- PhenixID MFA server will validate the password (against the user directory) and the OTP

- If validation is ok, user will be logged in.

 

NB! This scenario can also be used for username+OTP based logins.

To use the API, one method is called. It will return:

- HTTP Status code 200 + OTP if ok

- HTTP Status code 403 if not ok

Prerequisites

- PhenixID Authentication Services HTTP API configured for "get OTP based on called-in phone number" use case

Authentication

The API is always protected by authentication. The authentication mechanism may differ in different environments. It can be basic authentication, client certificate authentication or oAuth2 Bearer token.

Please consult the PhenixID administrator in your environment to find information about authentication method.

Data to be fetched before api call

The api client must fetch this value:

- phonenumber - The phone number of the called-in user. Should preferably be formatted the same way as stored in the user directory.

 How this parameter is fetched may differ depending on the use case.

getOTP - api call

Request

Method: HTTP PUT

Endpoint: /api/authentication/getOTP

Headers:

Name Value
 Mandatory Comment
Content-Type application/json Yes
tenant t1 Yes .Value must be given to you by PhenixID Signing Service admin, it might differ depending on the environment.
Authorization Bearer <access_token>

OR

Basic authentication string		 No

Body:

{ "phonenumber":"<mobile_phone_number>" }

Example request

 

PUT /api/authentication/getOTP HTTP/1.1
Host: integration.phenixid.se
tenant: t1
Content-Type: application/json
cache-control: no-cache

{ "phonenumber":"+467012345678" }

 

 

Response

The API consumer must check the http response status code and the response body

Possible http response status codes

1. 200. OTP generation ok.

2. 403. OTP generation not ok. Please contact your PhenixID admin.

 

Response body:

{ "otp":"<the_one_time_password>" }

 

Example response: 

{
    "otp": "532190"
}