Next Step Server REST API Reference

PowerAuth 2.0 Web Flow Server communicates with the Next Step Server via a REST API to resolve the next step in the authentication process. This chapter defines the REST API implemented by Next Step Server and consumed by the Web Flow Server during authentication.

The Next Step API can list available authentication methods and enable/disable authentication methods per user.

The Next Step API is also used by other services involved in the authentication process (e.g. Mobile Token or a party initiating a new operation). The API can be used to query operation details, update an operation (move it to the next step) as well as update operation formData as the user progresses in the authentication and authorization process.

Status codes and error handling

PowerAuth 2.0 Web Auth Server uses a unified format for error response body, accompanied with an appropriate HTTP status code. Besides the HTTP error codes that application server may return regardless of server application (such as 404 when resource is not found or 503 when server is down).

The list of error status codes:

Code	Description
200	OK response - REST API call succeeded
500	Server error - details in the message

All error responses that are produced by the Next Step Server have following body:

{
    "status": "ERROR",
    "responseObject": {
        "code": "ERROR_CODE",
        "message": "ERROR_MESSAGE_I18N_KEY"
    }
}

Authentication methods

List authentication methods

Lists all authentication methods supported by the server.

Method	`POST`
Resource URI	`/auth-method/list`

Request

Headers:
- Content-Type: application/json

{
    "requestObject": {        
    }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "authMethods": [
      {
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null
      },
      {
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null
      },
      {
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.username_password"
      },
      {
        "authMethod": "POWERAUTH_TOKEN",
        "hasUserInterface": true,
        "displayNameKey": "method.powerauth_token"
      },
      {
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.show_operation_detail"
      },
      {
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.sms_key"
      }
    ]
  }
}

List authentication methods enabled for given user

Lists all authentication methods enabled for given user.

Method	`POST`
Resource URI	`/user/auth-method/list`

Request

Headers:
- Content-Type: application/json

{
    "requestObject" : {  
        "userId": "12345678"
    }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "authMethods": [
      {
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null
      },
      {
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null
      },
      {
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.username_password"
      },
      {
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.show_operation_detail"
      },
      {
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.sms_key"
      }
    ]
  }
}

Enable an authentication method for given user

Enables an authentication method for given user and lists all authentication methods enabled for given user after the authentication method has been enabled.

Method	`POST`
Resource URI	`/user/auth-method`

Request

Headers:
- Content-Type: application/json

{
    "requestObject" : {
        "userId": "12345678",
        "authMethod": "POWERAUTH_TOKEN"
    }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "authMethods": [
      {
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null
      },
      {
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null
      },
      {
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.username_password"
      },
      {
        "authMethod": "POWERAUTH_TOKEN",
        "hasUserInterface": true,
        "displayNameKey": "method.powerauth_token"
      },
      {
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.show_operation_detail"
      },
      {
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.sms_key"
      }
    ]
  }
}

Disable an authentication method for given user

Disables an authentication method for given user and lists all authentication methods enabled for given user after the authentication method has been disabled.

Method	`DELETE`
Resource URI	`/user/auth-method`

Request

Headers:
- Content-Type: application/json

{
    "requestObject" : {
        "userId": "12345678",
        "authMethod": "POWERAUTH_TOKEN"
    }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "authMethods": [
      {
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null
      },
      {
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null
      },
      {
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.username_password"
      },
      {
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.show_operation_detail"
      },
      {
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.sms_key"
      }
    ]
  }
}

Operations

Operations contain following data:

operationName - name of the operations based on the purpose of the operation - different steps are defined for each operation name
operationId - unique ID of the operation, it is either set while creating an operation or it is generated
operationData - arbitrary string which contains data related for this operation, this data is not used during authorization and authentication
params - key-value pairs for additional parameters related to this operation
formData - data displayed by the UI as well as data gathered from the user responses (discussed in details below)

Operation formData

Operations contain formData which is a generic structure for storing input and output data for the operation.

The formData contains following sections:

static data - this data is set when the operation is created
dynamic data - this data is added as the operation progresses
user input - this data contains gathered inputs from the user as the authentication and authorization progresses

The static part of formData contains data related to the operation known when operation is initiated. For instance in case of a payment, the static data contains information about the payment such as title, amount, currency, target account and message to display to the user in the following structure:

{
  "formData": {
    "title": "Confirm Payment",
    "message": "Hello, please confirm payment 100 CZK to account 238400856/0300.",
    "parameters": [
      {
        "type": "AMOUNT",
        "label": "Amount",
        "amount": 100,
        "currency": "CZK"
      },
      {
        "type": "KEY_VALUE",
        "label": "To Account",
        "value": "238400856/0300"
      },
      {
        "type": "KEY_VALUE",
        "label": "Due Date",
        "value": "06/29/2017"
      },
      {
        "type": "MESSAGE",
        "label": "Note",
        "message": "Utility Bill Payment - 05/2017"
      }
    ]
  }
}

The dynamic part of formData contains additional data which is loaded once the user is authenticated. For instance in case of a payment, the dynamic data can contain choice of bank accounts available for the user with their balances:

{
  "formData": {
    "parameters": [
      {
        "type": "BANK_ACCOUNT_CHOICE",
        "label": "bankAccountChoice",
        "bankAccounts": [
          {
            "number": "12345678/1234",
            "name": "Běžný účet v CZK",
            "balance": 24394.52,
            "currency": "CZK",
            "usableForPayment": true,
            "unusableForPaymentReason": null
          },
          {
            "number": "87654321/4321",
            "name": "Spořící účet v CZK",
            "balance": 158121.1,
            "currency": "CZK",
            "usableForPayment": true,
            "unusableForPaymentReason": null
          },
          {
            "number": "44444444/1111",
            "name": "Spořící účet v EUR",
            "balance": 1.9,
            "currency": "EUR",
            "usableForPayment": false,
            "unusableForPaymentReason": "operationReview.balanceTooLow"
          }
        ]
      }
    ]
  }
}

The formData uses userInput JSON structure while gathering input from the user as the operation progresses:

{
  "formData": {
    "userInput": {
      "chosenBankAccountNumber": "12345678/1234",
      "chosenAuthMethod": "POWERAUTH_TOKEN",
      "offlineModeEnabled": "true"
    }
  }
}

Create an operation

Creates an operation in Next Step server.

Method	`POST`
Resource URI	`/operation`

Request

Headers:
- Content-Type: application/json

{
  "requestObject" : {
    "operationName" : "authorize_payment",
    "operationId" : null,
    "operationData" : {"amount":100,"currency":"CZK","account":"238400856/0300","note":"Utility Bill Payment - 05/2017"},
    "params": [],
    "formData": {
      "title": "Confirm Payment",
      "message": "Hello, please confirm payment 100 CZK to account 238400856/0300.",
      "parameters": [
        {
          "type": "AMOUNT",
          "label": "Amount",
          "amount": 100,
          "currency": "CZK"
        },
        {
          "type": "KEY_VALUE",
          "label": "To Account",
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "label": "Due Date",
          "value": "06/29/2017"
        },
        {
          "type": "MESSAGE",
          "label": "Note",
          "message": "Utility Bill Payment - 05/2017"
        }
      ]
    }
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "operationId": "460cfc04-e088-4769-8489-0a768f534f85",
    "operationName": "authorize_payment",
    "result": "CONTINUE",
    "resultDescription": null,
    "timestampCreated": "2017-07-17T19:43:19Z",
    "timestampExpires": "2017-07-17T19:48:19Z",
    "operationData": {"amount":100,"currency":"CZK","account":"238400856/0300","note":"Utility Bill Payment - 05/2017"},
    "steps": [
      {
        "authMethod": "USER_ID_ASSIGN",
        "params": []
      },
      {
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "params": []
      }
    ],
    "formData": {
      "title": "Confirm Payment",
      "message": "Hello, please confirm payment 100 CZK to account 238400856/0300.",
      "parameters": [
        {
          "type": "AMOUNT",
          "label": "Amount",
          "amount": 100,
          "currency": "CZK"
        },
        {
          "type": "KEY_VALUE",
          "label": "To Account",
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "label": "Due Date",
          "value": "06/29/2017"
        },
        {
          "type": "MESSAGE",
          "label": "Note",
          "message": "Utility Bill Payment - 05/2017"
        }
      ]
    },
    "expired": false
  }
}

Update an operation

Updates an operation in Next Step server.

Method	`PUT`
Resource URI	`/operation`

Request

Headers:
- Content-Type: application/json

{
  "requestObject" : {
    "operationId": "460cfc04-e088-4769-8489-0a768f534f85",
    "userId": "12345678",
    "authMethod": "USERNAME_PASSWORD_AUTH",
    "authStepResult": "CONFIRMED",
    "params": []
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": {
    "operationId": "460cfc04-e088-4769-8489-0a768f534f85",
    "userId": "12345678",
    "authMethod": "authorize_payment",
    "result": "CONTINUE",
    "resultDescription": null,
    "timestampCreated": "2017-07-17T19:43:19Z",
    "timestampExpires": "2017-07-17T19:48:19Z",
    "operationData": {"amount":100,"currency":"CZK","account":"238400856/0300","note":"Utility Bill Payment - 05/2017"},
    "steps": [
      {
        "authMethod": "SHOW_OPERATION_DETAIL",
        "params": [
        ]
      }
    ],
    "formData": {
      "title": "Confirm Payment",
      "message": "Hello, please confirm payment 100 CZK to account 238400856/0300.",
      "parameters": [
        {
          "type": "AMOUNT",
          "label": "Amount",
          "amount": 100,
          "currency": "CZK"
        },
        {
          "type": "KEY_VALUE",
          "label": "To Account",
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "label": "Due Date",
          "value": "06/29/2017"
        },
        {
          "type": "MESSAGE",
          "label": "Note",
          "message": "Utility Bill Payment - 05/2017"
        }
      ]
    },
    "expired": false
  }
}

Operation detail

Retrieves detail of an operation in the Next Step server.

Method	`POST`
Resource URI	`/operation/detail`

Request

Headers:
- Content-Type: application/json

{
  "requestObject" : {
    "operationId": "460cfc04-e088-4769-8489-0a768f534f85"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status" : "OK",
  "responseObject" : {
    "operationId" : "5acaa49a-a804-468c-a606-7832219c720e",
    "operationName" : "authorize_payment",
    "userId" : "roman",
    "result" : "CONTINUE",
    "timestampCreated" : "2017-10-19T11:26:47Z",
    "timestampExpires" : "2017-10-19T11:31:57Z",
    "operationData" : "{\"amount\":100,\"currency\":\"CZK\",\"account\":\"238400856/0300\",\"note\":\"Utility Bill Payment - 05/2017\"}",
    "steps" : [ {
      "authMethod" : "POWERAUTH_TOKEN",
      "params" : [ ]
    }, {
      "authMethod" : "SMS_KEY",
      "params" : [ ]
    } ],
    "history" : [ {
      "authMethod" : null,
      "authResult" : "CONTINUE",
      "requestAuthStepResult" : null
    }, {
      "authMethod" : "USERNAME_PASSWORD_AUTH",
      "authResult" : "CONTINUE",
      "requestAuthStepResult" : "CONFIRMED"
    } ],
    "formData" : {
      "title" : "Confirm Payment",
      "message" : "Hello, please confirm payment 100 CZK to account 238400856/0300.",
      "parameters" : [ {
        "type" : "AMOUNT",
        "label" : "Amount",
        "amount" : 100,
        "currency" : "CZK"
      }, {
        "type" : "KEY_VALUE",
        "label" : "To Account",
        "value" : "238400856/0300"
      }, {
        "type" : "KEY_VALUE",
        "label" : "Due Date",
        "value" : "06/29/2017"
      }, {
        "type" : "MESSAGE",
        "label" : "Note",
        "message" : "Utility Bill Payment - 05/2017"
      }, {
        "type" : "BANK_ACCOUNT_CHOICE",
        "label" : "bankAccountChoice",
        "bankAccounts" : [ {
          "number" : "12345678/1234",
          "name" : "Běžný účet v CZK",
          "balance" : 24394.52,
          "currency" : "CZK",
          "usableForPayment" : true,
          "unusableForPaymentReason" : null
        }, {
          "number" : "87654321/4321",
          "name" : "Spořící účet v CZK",
          "balance" : 158121.1,
          "currency" : "CZK",
          "usableForPayment" : true,
          "unusableForPaymentReason" : null
        }, {
          "number" : "44444444/1111",
          "name" : "Spořící účet v EUR",
          "balance" : 1.9,
          "currency" : "EUR",
          "usableForPayment" : false,
          "unusableForPaymentReason" : "operationReview.balanceTooLow"
        } ],
        "chosenBankAccountNumber" : "12345678/1234",
        "choiceDisabled" : true
      } ],
      "dynamicDataLoaded" : true,
      "userInput" : {
        "chosenBankAccountNumber" : "12345678/1234",
        "chosenAuthMethod" : "POWERAUTH_TOKEN",
        "offlineModeEnabled" : "false"
      }
    },
    "expired" : false
  }
}

List pending operations

Lists pending operation for given user and authentication method.

Method	`POST`
Resource URI	`/operation/list`

Request

Headers:
- Content-Type: application/json

{
  "requestObject" : {
    "userId" : "12345678",
    "authMethod" : "POWERAUTH_TOKEN"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": [
    {
      "operationId": "5acaa49a-a804-468c-a606-7832219c720e",
      "operationName": "authorize_payment",
      "userId": "12345678",
      "result": "CONTINUE",
      "timestampCreated": "2017-10-19T11:26:47Z",
      "timestampExpires": "2017-10-19T11:31:57Z",
      "operationData": "{\"amount\":100,\"currency\":\"CZK\",\"account\":\"238400856/0300\",\"note\":\"Utility Bill Payment - 05/2017\"}",
      "steps": [
      ],
      "history": [
      ],
      "formData": {
        "title": "Confirm Payment",
        "message": "Hello, please confirm payment 100 CZK to account 238400856/0300.",
        "parameters": [
          {
            "type": "AMOUNT",
            "label": "Amount",
            "amount": 100,
            "currency": "CZK"
          },
          {
            "type": "KEY_VALUE",
            "label": "To Account",
            "value": "238400856/0300"
          },
          {
            "type": "KEY_VALUE",
            "label": "Due Date",
            "value": "06/29/2017"
          },
          {
            "type": "MESSAGE",
            "label": "Note",
            "message": "Utility Bill Payment - 05/2017"
          },
          {
            "type": "BANK_ACCOUNT_CHOICE",
            "label": "bankAccountChoice",
            "bankAccounts": [
              {
                "number": "12345678/1234",
                "name": "Běžný účet v CZK",
                "balance": 24394.52,
                "currency": "CZK",
                "usableForPayment": true,
                "unusableForPaymentReason": null
              },
              {
                "number": "87654321/4321",
                "name": "Spořící účet v CZK",
                "balance": 158121.1,
                "currency": "CZK",
                "usableForPayment": true,
                "unusableForPaymentReason": null
              },
              {
                "number": "44444444/1111",
                "name": "Spořící účet v EUR",
                "balance": 1.9,
                "currency": "EUR",
                "usableForPayment": false,
                "unusableForPaymentReason": "operationReview.balanceTooLow"
              }
            ],
            "chosenBankAccountNumber": "12345678/1234",
            "choiceDisabled": true
          }
        ],
        "dynamicDataLoaded": true,
        "userInput": {
          "chosenBankAccountNumber": "12345678/1234",
          "chosenAuthMethod": "POWERAUTH_TOKEN",
          "offlineModeEnabled": "false"
        }
      },
      "expired": false
    }
  ]
}

Update operation formData

Updates operation formData for given operation.

Method	`PUT`
Resource URI	`/operation/formData`

Request

Headers:
- Content-Type: application/json

{
  "requestObject": {
    "operationId": "5acaa49a-a804-468c-a606-7832219c720e",
    "formData": {
      "title": "Confirm Payment",
      "message": "Hello, please confirm payment 100 CZK to account 238400856/0300.",
      "parameters": [
        {
          "type": "AMOUNT",
          "label": "Amount",
          "amount": 100,
          "currency": "CZK"
        },
        {
          "type": "KEY_VALUE",
          "label": "To Account",
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "label": "Due Date",
          "value": "06/29/2017"
        },
        {
          "type": "MESSAGE",
          "label": "Note",
          "message": "Utility Bill Payment - 05/2017"
        },
        {
          "type": "BANK_ACCOUNT_CHOICE",
          "label": "bankAccountChoice",
          "bankAccounts": [
            {
              "number": "12345678/1234",
              "name": "Běžný účet v CZK",
              "balance": 24394.52,
              "currency": "CZK",
              "usableForPayment": true,
              "unusableForPaymentReason": null
            },
            {
              "number": "87654321/4321",
              "name": "Spořící účet v CZK",
              "balance": 158121.1,
              "currency": "CZK",
              "usableForPayment": true,
              "unusableForPaymentReason": null
            },
            {
              "number": "44444444/1111",
              "name": "Spořící účet v EUR",
              "balance": 1.9,
              "currency": "EUR",
              "usableForPayment": false,
              "unusableForPaymentReason": "operationReview.balanceTooLow"
            }
          ],
          "chosenBankAccountNumber": "12345678/1234",
          "choiceDisabled": true
        }
      ],
      "dynamicDataLoaded": true,
      "userInput": {
        "chosenBankAccountNumber": "12345678/1234",
        "chosenAuthMethod": "POWERAUTH_TOKEN",
        "offlineModeEnabled": "false"
      }
    }
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status" : "OK",
  "responseObject" : null
}

Overview

Applications

REST APIs

Deployment

Customizing Web Flow

Technical Notes

Development

Compilation, Packaging and Deployment

Releases

Uh oh!

Next Step Server REST API Reference

Status codes and error handling

Authentication methods

List authentication methods

Request

Response

List authentication methods enabled for given user

Request

Response

Enable an authentication method for given user

Request

Response

Disable an authentication method for given user

Request

Response

Operations

Operation formData

Create an operation

Request

Response

Update an operation

Request

Response

Operation detail

Request

Response

List pending operations

Request

Response

Update operation formData

Request

Response

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally