Skip to content

Next Step Server REST API Reference

Jump to bottom
Roman Štrobl edited this page Oct 19, 2017 · 69 revisions

PowerAuth 2.0 Web Auth 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 Auth Server during authentication.

The Next Step Server API is also used by other services involved in the authentication process (e.g. Mobile Token).

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

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 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": "460cfc04-e088-4769-8489-0a768f534f85",
        "operationName": "authorize_payment",
        "userId": null,
        "result": "CONTINUE",
        "timestampCreated": "2017-08-06T10:43:28Z",
        "timestampExpires": "2017-08-06T10:48:28Z",
        "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": [
                ]
            }
        ],
        "history": [
            {
                "authMethod": null,
                "authResult": "CONTINUE"
            }
        ],
        "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
    }
}

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": "0f339ebd-0831-4a88-bdfb-65fba7a96b00",
            "operationName": "authorize_payment",
            "userId": "12345678",
            "result": "CONTINUE",
            "timestampCreated": "2017-08-06T10:48:43Z",
            "timestampExpires": "2017-08-06T10:53:49Z",
            "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"
                    }
                ]
            },
            "expired": false
        }
    ]
}

Overview

Applications

REST APIs

Deployment

Customizing Web Flow

Technical Notes

Development

Releases

Clone this wiki locally