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"
}