PhenixID DocumentationPhenixID Authentication ServicesTechnical overviewModulesAuthentication API - com.phenixidentity~phenix-api-authenticate

Authentication API - com.phenixidentity~phenix-api-authenticate

The com.phenixidentity~phenix-api-authenticate module allows for API based integration through HTTP(S). This is often from a third party application requiring advanced configuration.

Basic information

In some cases there are reasons why an application or a third party vendor need a custom authentication mechanism. This is when com.phenixidentity~phenix-api-authenticate  module can help. It allows for extrem flexibility and can serve multiple clients/tenants. 

The call from a client will result in the execution of PIPE. Based on the result from the PIPE the calling client can take appropriate action (allow/reject) t. 


Description Mandatory
Name of the module Yes
id Unique id of the module Yes
Custom configuration section
The http listener used Yes
tenant Configuration used to identify calling client and verify their  access when calling.
List of tenants.
    "name": "com.phenixidentity~phenix-api-authenticate",
    "id": "api_module",
    "config": {
        "http_configuration_ref": "d8baaa02-2ead-473c-88b8-a7aa08a53332",
        "tenant": [{
                "id": "default",
                "displayName": "PhenixID",
                "allowedOperation": ["authenticate"]
Click to copy

Tenant configuration

At least one tenant needs to be configured in order for the API to work. Two mandatory attributes are mandatory:

  • id
  •  allowedOperation 
Name Desciption Mandatory
id tenant identifier.  yes
A list of allowed operations executed by this tenant. Operation is equal to the last part of the URI. yes

Calling the API

All api calls has the base URI of <host_port>/api/authentication/<operation>. All operations must be made using HTTP method PUT.

Required headers are:

  • tenant - with the value used as id in tenant configuration
  • Content-Type with value of "application/json"

The ending part of the URI is automatically mapped to a PIPE with the same id the last part of the URI.

Sending data

Data can be sent to the API by setting key/values using json in the HTTP body

Click to copy

Only strings are allowed. Deep json structures is not supported.


Three possible response codes can be received:

  • 200 - all is good
  • 403 - something went wrong. See log for more info.
  • 500 - a general server failure. See log for more info.

Getting data back

If required data can be sent back to the client. to enable this ensure that the executing pipe returns a single item with the data required.

It will be sent back as JSON to the HTTP API.