PhenixID DocumentationPhenixID Authentication ServicesSolutionsDeveloper integration guidesUsing PhenixID HTTP API for PhenixID OneTouch authentication (push)

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