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