Skip to content

Data Adapter REST API Reference

Jump to bottom
Roman Štrobl edited this page Mar 20, 2018 · 32 revisions

PowerAuth 2.0 Web Auth Server communicates with the Data Adapter via a REST API. This chapter defines the REST API implemented by Data Adapter and consumed by the Web Auth Server.

Following topics are covered in this chapter:

Status codes and error handling

PowerAuth 2.0 compliant Data Adapter 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).

All error responses that are produced by the Data Adapter should have following body:

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

Expected error messages are explained in details in individual sections.

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-data-adapter",
        "applicationDisplayName" : "PowerAuth 2.0 Data Adapter",
        "applicationEnvironment" : "",
        "timestamp" : "2017-03-14T14:54:14Z"
    }  
}
  • applicationName - Application name.
  • applicationDisplayName - Application display name.
  • applicationEnvironment - Application environment.
  • timestamp - Response timestamp.

Authentication

Performs an authentication operation with username and password.

Method POST
Resource URI /api/auth/user/authenticate

The list of expected status codes during authentication:

Code Description
200 OK response - user was successfully authenticated
400 Invalid input - username and/or password has invalid format, unsupported authentication type
401 Authentication failed - provide reason in the message in case it is available
500 Server errors - provide error details in the message, this is only for unexpected errors

Request

  • Headers:
    • Content-Type: application/json
{
    "requestObject": {
        "username": "userxyz",
        "password": "s3cret",
        "type": "BASIC"
    }
}
  • The only currently supported authentication method is BASIC, however this field is present for future extensions of the API.

Response - authentication succeeded

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

The userId value is a system-wide unique identifier identifying the user who was just authenticated.

Response - authentication failed

This message should be sent when the Data Adapter receives a correct message, however the username and password combination is invalid.

  • Status Code: 401
  • Headers:
    • Content-Type: application/json
{
    "status": "ERROR",
    "responseObject": {
        "code": "AUTHENTICATION_FAILED",
        "message": "login.authenticationFailed",
        "validationErrors": null
    }
}

Response - input validation errors

This error should be returned when username or password format is invalid - either it contains unsupported characters or it is empty or too long. This error is also used when authentication type is not supported.

  • Status Code: 400
  • Headers:
    • Content-Type: application/json
{
    "status": "ERROR",
    "responseObject": {
        "code": "INPUT_INVALID",
        "message": "login.password.empty",
        "validationErrors": ["login.password.empty.authenticationRequest.password", "login.password.empty.password", "login.password.empty.java.lang.String", "login.password.empty"]
    }
}

For more information, see classes AuthenticationRequestValidator and DefaultExceptionResolver.

Response - internal error

This error should be used for all unexpected errors.

  • Status Code: 500
  • Headers:
    • Content-Type: application/json
{
    "status": "ERROR",
    "responseObject": {
        "code": "ERROR_GENERIC",
        "message": "Exception occurred at ...",
        "validationErrors": null
    }
}

User Information

Fetches user details based on user ID.

Method POST
Resource URI /api/auth/user/info

The list of expected status codes:

Code Description
200 OK response - user details have been successfully retrieved
401 Invalid request - userId is missing or invalid
404 User not found - user with given userId does not exit
500 Server errors - provide error details in the message, this is only for unexpected errors

Request

  • Headers:
    • Content-Type: application/json
{
    "requestObject": {
        "id": "12345678"
    }
}

Response - user info successfully retrieved

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
    "status": "OK",
    "responseObject": {
         "id":"12345678",
         "givenName":"John",
         "familyName":"Doe"
    }
}

SMS Authorization

Create SMS OTP messages and verify authorization code.

Create SMS - request parameters

Method POST
Resource URI /api/auth/sms/create

The list of expected status codes:

Code Description
200 OK response - SMS message has been successfully created
400 Invalid request - the request failed validation
500 Server errors - provide error details in the message, this is only for unexpected errors

Create SMS - request

  • Headers:
    • Content-Type: application/json
{
  "requestObject": {
    "operationId": "da3d1314-8852-4a93-bdbd-553177d5f76b",
    "userId": "12345678",
    "operationName": "authorize_payment",
    "operationFormData": ...,
    "lang": "en"
  }
}

Response - SMS has been successfully created

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status": "OK",
  "responseObject": {
    "messageId": "b750f8ae-5bca-48aa-ba8b-92c00e99ba29"
  }
}

Verify SMS - request parameters

Method POST
Resource URI /api/auth/sms/verify

The list of expected status codes:

Code Description
200 OK response - SMS message has been successfully verified
400 Invalid request - the request failed validation
500 Server errors - provide error details in the message, this is only for unexpected errors

Verify SMS - request

  • Headers:
    • Content-Type: application/json
{
  "requestObject": {
    "messageId": "5f9f5c01-8f0b-40c5-8ecc-40528a10460e",
    "authorizationCode": "23339372"
  }
}

Response - SMS has been successfully verified

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

FormData Change Notification

Notification of Data Adapter about formData change.

Request parameters

Method POST
Resource URI /api/operation/formData/change

The list of expected status codes:

Code Description
200 OK response - notification was successfully received
500 Server errors - provide error details in the message, this is only for unexpected errors

Request

  • Headers:
    • Content-Type: application/json
{
  "requestObject": {
    "userId": "12345678",
    "operationId": "8d70f3c1-d920-408f-bc57-e17d8ccb45d8",
    "formDataChange": {
      "type": "AUTH_METHOD_CHOICE",
      "chosenAuthMethod": "SMS_KEY"
    }
  }
}

Response

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

Operation Change Notification

Notification of Data Adapter about operation change.

Request parameters

Method POST
Resource URI /api/operation/change

The list of expected status codes:

Code Description
200 OK response - notification was successfully received
500 Server errors - provide error details in the message, this is only for unexpected errors

Request

Possible operation changes are: DONE, CANCELED and FAILED.

  • Headers:
    • Content-Type: application/json
{
  "requestObject": {
    "userId": "12345678",
    "operationId": "8d70f3c1-d920-408f-bc57-e17d8ccb45d8",
    "operationChange": "DONE"
  }
}

Response

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

Bank Account List

Retrieve list of bank accounts.

Request parameters

Method POST
Resource URI /api/auth/account/list

The list of expected status codes:

Code Description
200 OK response - bank account list was successfully received
500 Server errors - provide error details in the message, this is only for unexpected errors

Request

  • Headers:
    • Content-Type: application/json
{
  "requestObject": {
    "userId": "12345678",
    "operationName": "authorize_payment",
    "operationId": "8d70f3c1-d920-408f-bc57-e17d8ccb45d8",
    "formData": ...
  }
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
  "status" : "OK",
  "responseObject" : {
    "userId" : "roman",
    "bankAccounts" : {
      "bankAccounts" : [ {
        "number" : "12345678/1234",
        "accountId" : "CZ4012340000000012345678",
        "name" : "Běžný účet v CZK",
        "balance" : 24394.52,
        "currency" : "CZK",
        "usableForPayment" : true,
        "unusableForPaymentReason" : null
      }, {
        "number" : "87654321/4321",
        "accountId" : "CZ4043210000000087654321",
        "name" : "Spořící účet v CZK",
        "balance" : 158121.10,
        "currency" : "CZK",
        "usableForPayment" : true,
        "unusableForPaymentReason" : null
      }, {
        "number" : "44444444/1111",
        "accountId" : "CZ4011110000000044444444",
        "name" : "Spořící účet v EUR",
        "balance" : 1.90,
        "currency" : "EUR",
        "usableForPayment" : false,
        "unusableForPaymentReason" : "Low account balance"
      } ],
      "enabled" : true,
      "defaultValue" : null
    }
  }
}

TODO - this method is not generic enough. We should provide a formData details service instead. See https://github.com/lime-company/powerauth-webflow/issues/106

Overview

Applications

REST APIs

Deployment

Customizing Web Flow

Technical Notes

Development

Releases

Clone this wiki locally