Inbox API

Inbox API allows delivery of simple text messages to mobile apps.

The PowerAuth application is always derived from credentials which are used when accessing the REST API, so the API can be used with multiple PowerAuth applications by switching REST API credentials.

Possible Error Codes

The API may return one of the following error codes:

HTTP Error Code Description
400 ERROR_INBOX Error related to working inbox.
400 ERROR_INBOX_NOT_FOUND Inbox was not found for given user / app.
400 ERROR_REQUEST Request did not pass validation (mandatory property missing, null/invalid value).
401 ERROR_UNAUTHORIZED Returned in the case authentication fails (invalid application credentials).
404 ERROR_NOT_FOUND Returned in the case URL is not present (calling wrong API).
500 ERROR_GENERIC Unknown error occurred while processing request.
500 ERROR_INTERNAL_API Communication with internal service failed.

Services

To send messages to inbox, you can use a simple API call addressed by the user ID.

post /v2/inbox/messages Send New Message

Send a new message to inbox to given user and notify the user via a push notification, unless supressed.

Request

{
  "userId": "$USER_ID",
  "type": "$TYPE",
  "subject": "$SUBJECT",
  "summary": "$SUMMARY",
  "body": "$BODY",
  "silent": false
}
Request Params
Attribute Type Description
userId* String User ID.
type* String Type of the message, either text or html.
subject* String Subject of the message.
summary* String Summary of the message.
body* String Body of the message, in simple HTML format.
silent boolean If set to true, the message is delivered in the inbox silently, without a push notification informing the user about the message. Default: false (inform the user).

Response

If the message is successfully sent, API returns additional information about the new message.

{
  "id": "8819ac31-ad29-40d1-ac60-1b54293abe61",
  "userId": "$USER_ID",
  "type": "$TYPE",
  "subject": "$SUBJECT",
  "summary": "$SUMMARY",
  "body": "$BODY",
  "timestamp": "$TIMESTAMP",
  "read": false
}
Attribute Type Description
id* String Inbox message ID.
userId* String User ID.
type* String Type of the message, either text or html.
subject* String Subject of the message.
summary* String Summary of the message.
body* String Body of the message, in simple HTML format.
timestamp* String Timestamp when message was created, in Unix format.
read* String Indication of if the message was ready by the user.

Sending a message to inbox failed due to business logic error.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INBOX",
    "message": "Missing subject field"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

get /v2/inbox/messages/${id} Get Message Details

Get a message from inbox by given ID.

Request

Path Params
Param Type Description
id* String Inbox message ID.

Response

Returns information about the message with provided ID.

{
  "id": "${ID}",
  "userId": "$USER_ID",
  "type": "$TYPE",
  "subject": "$SUBJECT",
  "summary": "$SUMMARY",
  "body": "$BODY",
  "timestamp": "$TIMESTAMP",
  "read": false
}
Attribute Type Description
id* String Inbox message ID.
userId* String User ID.
type* String Type of the message, either text or html.
subject* String Subject of the message.
summary* String Summary of the message.
body* String Body of the message, in simple HTML format.
timestamp* String Timestamp when message was created, in Unix format.
read* String Indication of if the message was ready by the user.

Sending a message to inbox can fail due to business logic error.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INBOX",
    "message": "Missing subject field"
  }
}

In case message with given ID was not found, or the system user who requested it is not authorized to access apps where the message is sent.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INBOX_NOT_FOUND",
    "message": "Inbox message was not found."
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}
Last updated on Jan 12, 2023 (23:34) View product
Search

1.7.x

PowerAuth Cloud