Select release
On this page:

Communication Services

View product v1.9.0

The PowerAuth Communication services consists of several services resource groups:

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).
400 ERROR_PUSH_MESSAGE Error related to sending push messages, e.g., “Title must not be blank.”
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.
500 ERROR_UNABLE_TO_CALL_UPSTREAM_SERVICE Error indicating failure in calling an upstream service, often due to misconfiguration.

This table includes additional specific errors related to sending messages and internal service issues, enhancing the clarity and comprehensiveness of the documentation for troubleshooting and API usage.

Push Messaging Services

post /v2/messages/send Send Push Message

Send a push notification message to a given user. The call to this API is asynchronous and the push notifications are sent in the background.

The maximum payload size push service can send to the APNS, FCM, or HMS is limited. Make sure to keep the message brief, and the additional content minimal.

Request

To send a push message, use the following data payload:

{
  "userId": "$USER_ID",
  "registrationId": "$REGISTRATION_ID",
  "silent": false,
  "title": "$PUSH_TITLE",
  "message": "$PUSH_MESSAGE",
  "sound": "$SOUND",
  "extras": {
    "comment": "Added to the push payload"
  }
}
Attribute Type Description
userId* String User ID to receive the push message
registrationId UUID Optional ID of the registration to which to send the push message. The registration must be associated with the user ID value.
silent Boolean Indicates if the message is silent or not. The default value is false (audible notification displayed in the notification center).
title String Title of the push notification. Required for non-silent push notifications.
message String Message body of the push notification. Required for non-silent push notifications.
sound String Sound used for the notification. The default value is default.
extras Map<String, Object> Arbitrary data payload sent alongside the notification. Items will be placed in the data object in the FCM notification and the root of the notification for APNS.

Response

Basic success response.

{
  "status": "OK"
}

Invalid request payload is returned in case error occurs.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_PUSH_MESSAGE",
    "message": "Unable to send push message. Title must not be blank."
  }
}

In case the request fails the basic validation, the response returns extended information about all the individual violations:

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Invalid method parameter value",
    "violations": [
      {
        "fieldName": "title",
        "invalidValue": "",
        "hint": "size must be between 1 and 255"
      }
    ]
  }
}

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

Inbox Services

Inbox services 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.

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 Dec 11, 2024 (10:24) View product
Search

1.9.x

PowerAuth Cloud