Data Adapter REST API Reference

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.

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.

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": {
      "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": "SMS_KEY"
      }
    },
    "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 - SMS message has been successfully created
500	Server errors - provide error details in the message, this is only for unexpected errors

Request

• Headers:
  • Content-Type: application/json

{
  "requestObject": {
    "userId": "roman",
    "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
}