HTTP Authentication API

Authentication API is based on HTTP. Requests are sent with the HTTP PUT method. Depending on authentication type or stage in the authentication process the request & response may differ. The basics of the request/response will still follow the same pattern.

In addition to authentication, tokens can be enrolled and deleted.

The achieve an authentication the pattern will be similar to what is described below.

Authentication with username, password & OTP sent over SMS

  1. Request is sent
    • This request will often contain data for validation of usernames and passwords.
  2. Response received (potentially containing additional identity data)
    • Outcome of the first request (OK/NOT OK). Body may contain data. Potential data in response is agreed at configuration time but can also be dynamically added.
  3. New request with additional authentication data
    • This request will often contain data used to validate an OTP from ether an SMS.
  4. Response received (telling if the OTP was correct)
    • Outcome of the second request (OK/NOT OK). Body may contain data. Potential data in response is agreed at configuration time but can also be dynamically added.


The last part of the URI is mapped to a PhenixID pipe that handles the actual authentication.

The request

Authentication always starts with a client sending a request to the server. The request has two required header, “tenant” and “Content-Type”.

Content-Type must have value of “application/json”.

tenant must have a value matching the module configuration.  

URL pattern is http(s)://<host>:<port_if_non_default>/api/ authentication/<operation>/.

In most cases data needs to be sent in addition to theoperation.Adding a JSON object to the HTTP body does this.

All data are expected to be String data types,“key”: ”value”.

Example http body:



The response

After sending the request a successful response would return http status 200. The response body contains either an empty JSON object, {}, or a JSON body with data that might be of use further in the authentication.


Using state

Doing authentications when multiple requests are required the server need some way of maintaining state (like a web browser using session cookies).

There are two ways of handling state:

  1. Adding a parameter to the body,session_alias.The session_alias is used as the equivalent to a browser cookie. Difference is that the client sets it.If sent in a request the server will associate that request with any other requests with the samesession_alias. There are built in measures ensure no other client can hi-jack a session alias other the intended one.
  2. Letting the PhenixID server creating a session. The response will then contain the session id, which the client then will add as a parameter,session_id, in the subsequent requests.

Depending on use case and requirements the server should be configured to handle one of the two possible methods.


Handling tokens

Tokens can be enrolled/assigned to users. This is done in two steps. 

  1. Request a token by calling “token/requesttoken/”. Body must have  “userid

The response will contain the id and secret of the token. The secret the must by entered in the PhenixID Pocket Pass app by the user.

Example response

  "id": "9a8ca2ff-7da9-42b7-aaf5-ec273fee42a1",
  "secret": "VBKPOPZQIHOLZHH5",
  "assignedTo": "aandren",
  "displayName": "aandren@customer",
  "status": "PENDING",
  "tokenType": "SWTOKEN",
  "type": "TOTP",
  "length": "6",
  "timeStep": "30",
  "epoch": "0",
  "mode": "1",
  "drift": "0"


Assigning the token to the user second request is required. Path is “/token/enrolltoken/” with body

	"tokenid":"id from prev request"

Note that the tokenid is only valid for 5 minutes after the request.

A enrolled token can be deleted by sending a delete request to “token/deletetoken/” with body:


Creating PhenixID OneTouch assignments

Path: onetouch/assign/

allowedOperation name: assign

Body must be in the format of a PhenixID One Touch JSON assignment.


assigned_to must be set to userid bound to onetouch token.

Example request:

PUT /api/authentication/onetouch/assign/ HTTP/1.1


Content-Type: application/json

tenant: phenixid

Authorization: Basic YWRmczphZGZz

Cache-Control: no-cache

{ "assigned_to": "XXX", "notify": "true", "ttl" : "1", "form": { "controls": [ { "id": "html", "type": "html", "value": "%3Cdiv%20style%3D%22background-color%3A%20%23ffffff%22%3E%0A%20%20%20%20%3Cspan%20style%3D%22font-family%3A%20arial%2Csans-serif%22%3EConfirm%20login%20for%20user%3A%20andebjo%3C%2Fspan%3E%0A%20%20%20%20%3C%2Fbr%3E%0A%20%20%20%20%3Cspan%20style%3D%22font-family%3A%20arial%2Csans-serif%22%3Eand%20service%3A%20Test%20application%3C%2Fspan%3E%0A%3C%2Fdiv%3E" }, { "id": "c", "type": "button", "value": "Yes", "action": "CONFIRM" }, { "id": "r", "type": "button", "value": "No", "action": "REJECT" } ] } }


Example response body:


    "id": "7170015e-0f38-43d6-bccb-570b49b7a380"



Verifying an PhenixID OneTouch assignment

Path: “onetouch/check/”

allowedOperation name: check 


  "id": "id from previous request"

Response body will contain status of the assignment. 

Three possible status codes:


 Example request:

PUT /api/authentication/onetouch/check/ HTTP/1.1


tenant: phenixid

Content-Type: application/json

Authorization: Basic YWRmczphZGZz

Cache-Control: no-cache

{ "id": "7170015e-0f38-43d6-bccb-570b49b7a380" }



Example response body:


    "assigned_to": "XXX",

    "notify": "true",

    "ttl": "1",

    "form": {

        "controls": [


                "id": "html",

                "type": "html",

                "value": "%3Cdiv%20style%3D%22background-color%3A%20%23ffffff%22%3E%0A%20%20%20%20%3Cspan%20style%3D%22font-family%3A%20arial%2Csans-serif%22%3EConfirm%20login%20for%20user%3A%20andebjo%3C%2Fspan%3E%0A%20%20%20%20%3C%2Fbr%3E%0A%20%20%20%20%3Cspan%20style%3D%22font-family%3A%20arial%2Csans-serif%22%3Eand%20service%3A%20Test%20application%3C%2Fspan%3E%0A%3C%2Fdiv%3E"



                "id": "c",

                "type": "button",

                "value": "Yes",

                "action": "CONFIRM"



                "id": "r",

                "type": "button",

                "value": "No",

                "action": "REJECT"




    "expires": "2017-07-11T13:01:19.547Z",

    "status": "PENDING",

    "id": "7170015e-0f38-43d6-bccb-570b49b7a380",

    "created": "2017-07-11T12:56:19.547Z"


Restricting client access

Restrictions are placed on the last part of the URI. The value of this string is compared to the “allowedOperation” section for each tenant. If the value is not found in the list the operation is discarded.

Error codes

Three error codes are possible:

  • 401 - authentication failed in some way. Http response body will contain an error message.
  • 401 - with the header WWW-Authenticate. Server is expecting basic authentication before executing the request. No information in the body
  • 500 General server error. Body will contain error message.

System authentication

Server can be configured to force http basic authentication, client certificate authentication or OAuth authentication for clients prior to executing any operation. Invalid authentication between client and server will generate an error and execution will be aborted.

To achieve system authentication, add a configuration parameter to the module, callerVerificationPipe, with the id of a pipe that will verify api-client credentials. 


When using HTTP Basic Authentication, the API module will fetch the username and password from the Authorization header. Username and password will be passed to the callerVerificationPipe (and allowedOperation pipes) using request parameters username_api and password_api. 

Module installation

            "module": "com.phenixidentity~phenix-api-authenticate",
            "enabled": "true",
            "config": {
                "tenant": [{
                        "id": "default",
                        "displayName": "PhenixID",
                        "callerVerificationPipe" : "pipeValidateClientCert",
                        "allowedOperation": [“operation_one”,” operation_two”]
                "http_configuration_ref" : "idHttpConf" //Http connection pointer. If omitted, it will inherit port/ssl from http authentication module.

The parameter tenant is of type array to make this feature multi-tenant.

Tenant parameters explained

Parameter name Description Mandatory
id The id of the tenant Yes
displayName Tenant display name No
allowedOperation List of operations a tenant is allowed to call. An operation maps to a pipe id with two exceptions:
assign - trigger onetouch authentication
check - check onetouch authentication status
requesttoken - start Pocket Pass enrollment
enrolltoken - 
enroll Pocket Pass
deletetoken - 
remove Pocket Pass token
start - start OneTouch enrollment
enrollstatus - check OneTouch enrollment status
callerVerificationPipe Id of pipe that will verify api client authentication. This pipe will be executed before the target operation No

Patch for 3.2

This patch will fix problems with callerVerificationPipe for PAS version 3.2.

To apply the patch:

- Shut down the service

- Download the attached class

- Replace class file in <pas_root>/mods/com.phenixidentity~phenix-api-authenticate~3.2.0/com/phenixidentity/api/authenticate/handler(