Using PhenixID HTTP API for PhenixID OneTouch authentication (push)
Overview
To use the API, two methods must be called. The first API method call is to trigger the authentication. This will return an assignment ID value. The second API method call will poll the status of the authentication. The API client must poll the authentication until a authentication-process-done status is returned.
Prerequisites
- PhenixID Authentication Services HTTP API for OneTouch authentication configured
- PhenixID OneTouch app installed
- PhenixID OneTouch enrolled for a user
- If PhenixID Authentication Services HTTP API is protected with client certificate authentication: Client certificate (p12)
- If PhenixID Authentication Services HTTP API is protected with basic authentication: Username and password
Trigger authentication - data to be fetched before api call
To trigger OneTouch authentication, the api client must fetch this value:
- The userID (must match the userID of the PhenixID OneTouch profile)
Trigger authentication - api call
Request
Method: HTTP PUT
Endpoint: /api/authentication/onetouch_start_auth
Headers:
| Name | Value |
Mandatory | Comment |
|---|---|---|---|
| Content-Type | application/json | Yes | |
| tenant | t1 | Yes | .Value must be given to you by PhenixID Authentication Services admin, it might differ depending on the environment. |
| Authorization | <basic_auth_value> | No | If applicable, username and password must be given to you by PhenixID Authentication Services admin. |
Body:
The body must contains a json structure.
{
"username":".."
} Json structure properties:
| Name | Example value | Mandatory | Comment |
|---|---|---|---|
| username | wgretzky | Yes | The userID. Must match the PhenixID OneTouch profile userID. |
Example request (Please note that authorization data is not included in this example).
PUT /api/authentication/onetouch_start_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ "username":"wgretzky" }Response
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3900
{
"assignmentid":"667b2455-6cdf-4f7e-885d-fc9512ac735f"
}Poll authentication status - use assignment id
The API client must fetch the assignmentid returned by the Trigger authentication call.
The API client must call the Poll authentication status API method periodically while status is PENDING or IN_PROGRESS.
Poll authentication status - api call
Request
Method: HTTP PUT
Endpoint: /api/authentication/onetouch_check_auth
Headers:
| Name | Value | Mandatory | Comment |
|---|---|---|---|
| Content-Type | application/json | Yes | |
| tenant | t1 | Yes | This value must be given to you by the PhenixID Signing Service admin. |
| Authorization | <basic_auth_value> | No | Basic authentication username and password must be given to you by PhenixID Signing Service admin. |
Body:
The body must contains a json structure.
{"assignmentid":"..."} Json structure properties:
| Name | Value | Mandatory | Comment |
|---|---|---|---|
| assignment | <Value_returned_from_trigger_auth> | Yes |
Example request (Please note that authorization data is not included in this example).
PUT /api/authentication/onetouch_check_auth HTTP/1.1
Host: demo.phenixid.net
Content-Type: application/json
tenant: t1
Cache-Control: no-cache
{ "assignmentid": "667b2455-6cdf-4f7e-885d-fc9512ac735f" }Response
Response
The response body JSON structure properties:
| Name | Possible values | Comment |
|---|---|---|
| status | PENDING IN_PROGRESS CONFIRMED REJECTED ERROR |
PENDING -> User did not yet open the OneTouch app. Continue to poll. IN_PROGRESS -> User opened the OneTouch app. Continue to poll. CONFIRMED -> Successful authentication REJECTED-> User denied the authentication request. ERROR-> Something went wrong. |
Please note that the response may be augmented with additional properties, such as a user directory lookup result, based on configuration. Please contact the PhenixID Authentication Services administrator to retrieve additional data.
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 390010
{
"status": "CONFIRMED"
}