Skip to content

Next Step Server REST API Reference

Jump to bottom
Roman Štrobl edited this page Nov 19, 2017 · 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 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": {
    "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
  • 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": {
      "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 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"
          }
        ]
      }
    ]
  }
}

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

Chosen authentication method for current step is stored in formData, too.

 "chosenAuthMethod": "POWERAUTH_TOKEN"

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 /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.

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.

<table>
    <tr>
        <td>Method</td>
        <td><code>PUT</code></td>
    </tr>
    <tr>
        <td>Resource URI</td>
        <td><code>/operation/chosenAuthMethod</code></td>
    </tr>
</table>

#### Request

- Headers:
    - `Content-Type: application/json`

```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