Skip to content

Next Step Server REST API Reference

Jump to bottom
Roman Štrobl edited this page Jan 14, 2018 · 69 revisions

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 REST API can be also used by other components.

The Next Step API can list available authentication methods and enable/disable authentication methods per user. Authentication method configuration can be updated - for instance the activation ID of registered user device is set for the Mobile Token authentication method.

The Next Step API is also used by other components 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, create an operation, update an operation (move it to the next step) as well as update operation formData and set chosen authentication method 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"
    }
}

Service Status

Get a system status response, with basic information about the running application.

Method GET
Resource URI /api/service/status

Response

{
    "status" : "OK",
    "responseObject": {
        "applicationName" : "powerauth-nextstep",
        "applicationDisplayName" : "PowerAuth 2.0 Next Step Server",
        "applicationEnvironment" : "",
        "timestamp" : "2017-03-14T14:54:14Z"
    }  
}
  • applicationName - Application name.
  • applicationDisplayName - Application display name.
  • applicationEnvironment - Application environment.
  • timestamp - Response timestamp.

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": {
    "userAuthMethods": [
      {
        "userId": "12345678",
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.usernamePassword",
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.showOperationDetail",
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "POWERAUTH_TOKEN",
        "hasUserInterface": true,
        "displayNameKey": "method.powerauthToken",
        "config": {
          "activationId": "bfab8028-ff7c-4451-b602-98e1179464cd"
        }
      },
      {
        "userId": "12345678",
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.smsKey",
        "config": null
      }
    ]
  }
}

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

The request contains three parameters:

  • userId - identification of the user
  • authMethod - name of the authentication method
  • config - configuration of the authentication method

Currently the only supported configuration is in the POWERAUTH_TOKEN method and it contains activationId, as seen on the sample request below.

  • Headers:
    • Content-Type: application/json
{
    "requestObject" : {
        "userId": "12345678",
        "authMethod": "POWERAUTH_TOKEN",
        "config": {"activationId": "bfab8028-ff7c-4451-b602-98e1179464cd"}
    }
}

For other authentication methods use the following configuration:

        "config": null

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status": "OK",
  "responseObject": {
    "userAuthMethods": [
      {
        "userId": "12345678",
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.usernamePassword",
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.showOperationDetail",
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "POWERAUTH_TOKEN",
        "hasUserInterface": true,
        "displayNameKey": "method.powerauthToken",
        "config": {"activationId": "bfab8028-ff7c-4451-b602-98e1179464cd"}
      },
      {
        "userId": "12345678",
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.smsKey",
        "config": null
      }
    ]
  }
}

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",
        "config": null
    }
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status": "OK",
  "responseObject": {
    "userAuthMethods": [
      {
        "userId": "12345678",
        "authMethod": "INIT",
        "hasUserInterface": false,
        "displayNameKey": null,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USER_ID_ASSIGN",
        "hasUserInterface": false,
        "displayNameKey": null,
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "USERNAME_PASSWORD_AUTH",
        "hasUserInterface": true,
        "displayNameKey": "method.usernamePassword",
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "SHOW_OPERATION_DETAIL",
        "hasUserInterface": true,
        "displayNameKey": "method.showOperationDetail",
        "config": null
      },
      {
        "userId": "12345678",
        "authMethod": "SMS_KEY",
        "hasUserInterface": true,
        "displayNameKey": "method.smsKey",
        "config": null
      }
    ]
  }
}

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 (required)
  • operationId - unique ID of the operation, it is either set while creating an operation or it is generated (field is required, value is optional, for generated operation use null as value)
  • operationData - arbitrary string which contains data related to this operation, this data is not used during authorization and authentication (required)
  • params - key-value pairs for additional parameters related to this operation (optional)
  • formData - data displayed by the UI as well as data gathered from the user responses (required, 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 (required)
  • dynamic data - this data is added as the operation progresses (optional)
  • user input - this data contains gathered inputs from the user as the authentication and authorization progresses (optional)

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": {
      "id": "operation.title",
      "value": "Confirm Payment"
    },
    "message": {
      "id": "operation.message",
      "value": "Hello, please confirm payment 100 CZK to account 238400856/0300."
    },
    "parameters": [
      {
        "type": "AMOUNT",
        "id": "operation.amount",
        "label": "Amount",
        "amount": 100,
        "currency": "CZK",
        "currencyId": "operation.currency"
      },
      {
        "type": "KEY_VALUE",
        "id": "operation.account",
        "label": "To Account",
        "value": "238400856/0300"
      },
      {
        "type": "KEY_VALUE",
        "id": "operation.dueDate",
        "label": "Due Date",
        "value": "06/29/2017"
      },
      {
        "type": "NOTE",
        "id": "operation.note",
        "label": "Note",
        "note": "Utility Bill Payment - 05/2017"
      },      
    ]
  }
}

The usage of static formData:

  • title - displayed as title on the page with operation details
    • field is required
    • id is the localization key
    • value is the localized text displayed on the page
  • message - displayed as message on the page with operation details
    • field is required
    • id is the localization key
    • value is the localized text displayed on the page
  • parameters - operation parameters which are displayed on the page with operation details
    • field is required, however the parameter list can be empty

Following parameter types are available:

  • AMOUNT - contains information about amount in this operation including currency
    • field is optional
    • id is the localization key
    • label is the displayed localized text
    • amount is displayed next to the label
    • currency is displayed next to the amount
    • currencyId is used internally for localization
  • NOTE - contains text message related to the operation
    • field is optional
    • id is the localization key
    • label is the displayed localized text
    • note is the text message displayed next to the label
  • KEY_VALUE
    • field is optional
    • id is the localization key
    • label is the displayed localized text
    • value is the text displayed next to the label

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",
        "id": "operation.bankAccountChoice",
        "label": "From Account",
        "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.10,
            "currency": "CZK",
            "usableForPayment": true,
            "unusableForPaymentReason": null
          },
          {
            "number": "44444444/1111",
            "name": "Spořící účet v EUR",
            "balance": 1.90,
            "currency": "EUR",
            "usableForPayment": false,
            "unusableForPaymentReason": "Low account balance"
          }
        ]
      }
    ]
  }
}

Following parameter types are available:

  • BANK_ACCOUNT_CHOICE
    • field is optional
    • id is the localization key
    • label is the displayed localized text
    • bankAccounts list is required when BANK_ACCOUNT_CHOICE parameter is specified, however it can be empty

Bank account details:

  • number - required, account number in human readable format
  • name - required, account name
  • balance - required, account balance
  • currency - required, account currency
  • usableForPayment - required, whether account can be used for payment, in case value is false, unusableForPaymentReason is displayed
  • unusableForPaymentReason - optional when usableForPayment = false, otherwise it is required, field explains reason why account is unusable for payment

When dynamic form data is loaded, the formData structure contains following data:

{
  "formData": {
    "dynamicDataLoaded": true
  }
}

Dynamic formData may not be loaded because it is required only for specific steps such as operation review. In this case the value is:

{
  "formData": {
    "dynamicDataLoaded": false
  }
}

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

{
  "formData": {
    "userInput": {
      "operation.bankAccountChoice": "87654321/4321",
      "operation.bankAccountChoice.disabled": "true",
      "offlineMode.enabled": "true"
    }
  }
}

The userInput part of formData is optional - empty value of userInput is:

{
  "formData": {
    "userInput": {
    }
  }
}

Chosen authentication method for current step is stored in formData in case it is available:

{
  "formData": {
    "chosenAuthMethod": "POWERAUTH_TOKEN"
  }
}

Null value is used when authentication method has not been chosen for current step:

{
  "formData": {
    "chosenAuthMethod": null
  }
}

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\",\"dueDate\":\"06/29/2017\"}",
    "params": [],
    "formData": {
      "title": {
        "id": "operation.title",
        "value": null
      },
      "message": {
        "id": "operation.message",
        "value": null
      },
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": null,
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": null,
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": null,
          "value": "06/29/2017"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": null,
          "note": "Utility Bill Payment - 05/2017"
        }
      ],
      "dynamicDataLoaded": false,
      "userInput": {}
    }
  }
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status" : "OK",
  "responseObject" : {
    "operationId" : "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
    "operationName" : "authorize_payment",
    "result" : "CONTINUE",
    "resultDescription" : null,
    "timestampCreated" : "2017-11-19T19:15:33Z",
    "timestampExpires" : "2017-11-19T19:20:33Z",
    "operationData" : null,
    "steps" : [ {
      "authMethod" : "USER_ID_ASSIGN",
      "params" : [ ]
    }, {
      "authMethod" : "USERNAME_PASSWORD_AUTH",
      "params" : [ ]
    } ],
    "formData" : {
      "title" : {
        "id" : "operation.title",
        "value" : null
      },
      "message" : {
        "id" : "operation.message",
        "value" : null
      },
      "parameters" : [ {
        "type" : "AMOUNT",
        "id" : "operation.amount",
        "label" : null,
        "amount" : 100,
        "currency" : "CZK",
        "currencyId" : "operation.currency"
      }, {
        "type" : "KEY_VALUE",
        "id" : "operation.account",
        "label" : null,
        "value" : "238400856/0300"
      }, {
        "type" : "KEY_VALUE",
        "id" : "operation.dueDate",
        "label" : null,
        "value" : "06/29/2017"
      }, {
        "type" : "NOTE",
        "id" : "operation.note",
        "label" : null,
        "note" : "Utility Bill Payment - 05/2017"
      } ],
      "dynamicDataLoaded" : false,
      "userInput" : { }
    },
    "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": "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
    "userId": "12345678",
    "authMethod": "USERNAME_PASSWORD_AUTH",
    "authStepResult": "CONFIRMED",
    "authStepResultDescription": null,
    "params": []
  }
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status": "OK",
  "responseObject": {
    "operationId": "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
    "operationName": "authorize_payment",
    "userId": "12345678",
    "result": "CONTINUE",
    "resultDescription": null,
    "timestampCreated": "2017-11-19T19:18:11Z",
    "timestampExpires": "2017-11-19T19:23:11Z",
    "steps": [
      {
        "authMethod": "POWERAUTH_TOKEN",
        "params": []
      },
      {
        "authMethod": "SMS_KEY",
        "params": []
      }
    ],
    "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": "3e87f071-2f08-4341-9034-47cb5f8a3fb4"
  }
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status": "OK",
  "responseObject": {
    "operationId": "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
    "operationName": "authorize_payment",
    "userId": "12345678",
    "result": "CONTINUE",
    "timestampCreated": "2017-11-19T19:15:34Z",
    "timestampExpires": "2017-11-19T19:23:11Z",
    "operationData": "{\"amount\":100,\"currency\":\"CZK\",\"account\":\"238400856/0300\",\"note\":\"Utility Bill Payment - 05/2017\",\"dueDate\":\"06/29/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": {
        "id": "operation.title",
        "value": null
      },
      "message": {
        "id": "operation.message",
        "value": null
      },
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": null,
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": null,
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": null,
          "value": "06/29/2017"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": null,
          "note": "Utility Bill Payment - 05/2017"
        }
      ],
      "dynamicDataLoaded": false,
      "userInput": {
        "operation.bankAccountChoice": "12345678/1234"
      }
    },
    "chosenAuthMethod": null,
    "expired": false
  }
}

List pending operations

Lists pending operation for given user and authentication method.

Method POST
Resource URI /user/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": "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
      "operationName": "authorize_payment",
      "userId": "12345678",
      "result": "CONTINUE",
      "timestampCreated": "2017-11-19T19:15:34Z",
      "timestampExpires": "2017-11-19T19:23:11Z",
      "operationData": "{\"amount\":100,\"currency\":\"CZK\",\"account\":\"238400856/0300\",\"note\":\"Utility Bill Payment - 05/2017\",\"dueDate\":\"06/29/2017\"}",
      "steps": [
      ],
      "history": [
      ],
      "formData": {
        "title": {
          "id": "operation.title",
          "value": null
        },
        "message": {
          "id": "operation.message",
          "value": null
        },
        "parameters": [
          {
            "type": "AMOUNT",
            "id": "operation.amount",
            "label": null,
            "amount": 100,
            "currency": "CZK",
            "currencyId": "operation.currency"
          },
          {
            "type": "KEY_VALUE",
            "id": "operation.account",
            "label": null,
            "value": "238400856/0300"
          },
          {
            "type": "KEY_VALUE",
            "id": "operation.dueDate",
            "label": null,
            "value": "06/29/2017"
          },
          {
            "type": "NOTE",
            "id": "operation.note",
            "label": null,
            "note": "Utility Bill Payment - 05/2017"
          }
        ],
        "dynamicDataLoaded": false,
        "userInput": {
          "operation.bankAccountChoice": "12345678/1234",
          "operation.bankAccountChoice.disabled": "true"
        }
      },
      "chosenAuthMethod": null,
      "expired": false
    }
  ]
}

Update operation formData

Updates operation formData for given operation. Only the userInput part of formData can be currently updated by the clients.

Method PUT
Resource URI /operation/formData

Request

  • Headers:
    • Content-Type: application/json
{
  "requestObject": {
    "operationId": "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
    "formData": {
      "title": {
        "id": "operation.title",
        "value": "Confirm Payment"
      },
      "message": {
        "id": "operation.message",
        "value": "Hello, please confirm payment 100 CZK to account 238400856/0300."
      },
      "parameters": [
        {
          "type": "AMOUNT",
          "id": "operation.amount",
          "label": "Amount",
          "amount": 100,
          "currency": "CZK",
          "currencyId": "operation.currency"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.account",
          "label": "To Account",
          "value": "238400856/0300"
        },
        {
          "type": "KEY_VALUE",
          "id": "operation.dueDate",
          "label": "Due Date",
          "value": "06/29/2017"
        },
        {
          "type": "NOTE",
          "id": "operation.note",
          "label": "Note",
          "note": "Utility Bill Payment - 05/2017"
        },
        {
          "type": "BANK_ACCOUNT_CHOICE",
          "id": "operation.bankAccountChoice",
          "label": "From Account",
          "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": "Low account balance"
            }
          ]
        }
      ],
      "dynamicDataLoaded": true,
      "userInput": {
        "operation.bankAccountChoice": "12345678/1234",
        "operation.bankAccountChoice.disabled": "true"
      }
    }
  }
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status" : "OK",
  "responseObject" : null
}

Set chosen authentication method

Sets chosen authentication method for current operation step.

Method PUT
Resource URI /operation/chosenAuthMethod

Request

  • Headers:
    • Content-Type: application/json
{
  "requestObject": {
    "operationId": "3e87f071-2f08-4341-9034-47cb5f8a3fb4",
    "chosenAuthMethod": "POWERAUTH_TOKEN"
  }
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status" : "OK",
  "responseObject" : null
}

Overview

Applications

REST APIs

Deployment

Customizing Web Flow

Technical Notes

Development

Releases

Clone this wiki locally