Select release
On this page:

Push Server API

Edit on Github Send Feedback v1.6.0

Push Server provides a RESTful API for the 3rd party integration purposes. The API contains methods related with:

Following endpoints are published in PowerAuth Push Server RESTful API:

Error Handling

PowerAuth Push Server uses following 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), following status codes may be returned:

Status HTTP Code Description
OK 200 No issue
ERROR 400 Issue with a request format, or issue of the business logic
ERROR 401 Unauthorized, invalid security token configuration

All error responses that are produced by the PowerAuth Push Server have following body:

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_GENERIC",
    "message": "Campaign with entered ID does not exist"
  }
}
  • status - OK, ERROR
  • code - ERROR_GENERIC, ERROR_DATABASE
  • message - Message that describes certain error.

Service

Describes basic information of application.

get /push/service/status Service Status

Send a system status response, with basic information about the running application.

Response

{
  "status": "OK",
  "responseObject": {
    "applicationName": "powerauth-push",
    "applicationDisplayName": "PowerAuth Push Server",
    "applicationEnvironment": "",
    "version": "0.21.0",
    "buildTime": "2019-01-22T14:59:14.954+0000",
    "timestamp": "2019-01-22T15:00:28.399+0000"
  }
}
  • applicationName - Application name.
  • applicationDisplayName - Application display name.
  • applicationEnvironment - Application environment.
  • version - Version of Push server.
  • buildTime - Timestamp when the powerauth-push-server.war file was built.
  • timestamp - Current time on application.

Device

Represents mobile device with iOS or Android that is capable to receive a push notification. Device has to first register with APNS or FCM to obtain push token. Then it has to forward the push token to the push server end-point. After that push server is able to send push notification to the device.

post /push/device/create Create Device

Create a new device push token (platform specific). The call must include activationId, so that the token is associated with given user in the PowerAuth Server.

Note: Since this endpoint is usually called by the back-end service, it is not secured in any way. It’s the service that calls this endpoint responsibility to assure that the device is somehow authenticated before the push token is assigned with given activation ID, so that there are no incorrect bindings.

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "token": "1234567890987654321234567890",
    "platform": "ios",
    "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412"
  }
}
  • appId - Application that device is using.
  • token - Identifier for device.
  • platform - ios, android
  • activationId - Activation identifier

Response

{
  "status": "OK"
}

post /push/device/create/multi Create Device for Multiple Activations

Create a new device push token (platform specific). The call must include activationIds which contains list of activations to be associated with the registered device.

Note: Since this endpoint is usually called by the back-end service, it is not secured in any way. It’s the service that calls this endpoint responsibility to assure that the device is somehow authenticated before the push token is assigned with given activation IDs, so that there are no incorrect bindings.

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "token": "1234567890987654321234567890",
    "platform": "ios",
    "activationIds": [
      "49414e31-f3df-4cea-87e6-f214ca3b8412",
      "26c94bf8-f594-4bd8-9c51-93449926b644"
    ]
  }
}
  • appId - Application that device is using.
  • token - Identifier for device.
  • platform - ios, android
  • activationIds - Associated activation identifiers

Response

{
  "status": "OK"
}

delete /push/device/remove Remove Device

Removes registered device based on the push token value.

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "token": "12456789098321234567890"
  }
}
  • appId - Application that device is using.
  • token - Identifier for device.

Response

{
  "status": "OK"
}

post /push/device/status/update Update Device Status

Update the status of given device registration based on the associated activation ID. This can help assure that registration is in non-active state and cannot receive personal messages.

Request

{
  "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412"
}
  • activationId - Identifier of activation.

Response

{
  "status": "OK"
}

Message

Represents a single notification sent to the device. It provides an abstraction of APNS or FCM message payload.

post /push/message/send Send Message

Send a single push message to given user via provided application, optionally to the specific device represented by given activationId.

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "mode": "SYNCHRONOUS",
    "message": {
      "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412",
      "userId": "123",
      "priority": "HIGH",
      "attributes": {
        "personal": true,
        "silent": true
      },
      "body": {
        "title": "Balance update",
        "titleLocKey": "balance.update.title",
        "titleLocArgs": [],
        "body": "Your balance is now $745.00",
        "bodyLocKey": "balance.update.body",
        "bodyLocArgs": [],
        "badge": 3,
        "sound": "default",
        "icon": "custom-icon",
        "category": "balance-update",
        "collapseKey": "balance-update",
        "validUntil": "2017-12-11T21:22:29.923Z",
        "extras": {
          "_comment": "Any custom data."
        }
      }
    }
  }
}
  • appId - Application that user/s is/are using.
  • mode - Mode of sending, default value is SYNCHRONOUS (response waits for all messages being sent), you can use ASYNCHRONOUS (return response immediately).
  • message - Body for notification creating.
    • activationId - Identifier of specific activation, that usually corresponds to the device.
    • userId - Identifier of user.
    • priority - Priority of the message, NORMAL or HIGH (default).
    • attributes - Set of boolean variables:
      • silent - Sent silent push notification (If true, no system UI is displayed).
      • personal - If true and activation is not in ACTIVE state the message is not sent.
    • body - Body object is described in here

Response

{
  "status": "OK",
  "responseObject": {
    "mode": "SYNCHRONOUS",
    "result": {
      "ios": {
        "sent": 1,
        "pending": 0,
        "failed": 0,
        "total": 1
      },
      "android": {
        "sent": 1,
        "pending": 0,
        "failed": 0,
        "total": 1
      }
    }
  }
}
  • mode - Used sending mode.
  • result - Information about sending notifications. Present only for SYNCHRONOUS mode.
    • sent - Number of sent notifications.
    • failed - Number of failed notifications.
    • pending - Number of notifications that are still pending sending.
    • total - Number of total notifications.

post /push/message/batch/send Send Message Batch

Sends a message batch - each item in the batch represents a message to given user. The message is sent via provided application (optionally to the specific device represented by given activationId).

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "mode": "SYNCHRONOUS",
    "batch": [
      {
        "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412",
        "userId": "123",
        "priority": "HIGH",
        "attributes": {
          "personal": true,
          "silent": true
        },
        "body": {
          "title": "Balance update",
          "titleLocKey": "balance.update.title",
          "titleLocArgs": [],
          "body": "Your balance is now $745.00",
          "bodyLocKey": "balance.update.body",
          "bodyLocArgs": [],
          "badge": 3,
          "sound": "default",
          "icon": "custom-icon",
          "category": "balance-update",
          "collapseKey": "balance-update",
          "validUntil": "2017-12-11T21:22:29.923Z",
          "extras": {
            "_comment": "Any custom data."
          }
        }
      },
      {
        "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412",
        "userId": "1234",
        "priority": "HIGH",
        "attributes": {
          "personal": true,
          "silent": true
        },
        "body": {
          "title": "Balance update",
          "titleLocKey": "balance.update.title",
          "titleLocArgs": [],
          "body": "Your balance is now $745.00",
          "bodyLocKey": "balance.update.body",
          "bodyLocArgs": [],
          "badge": 3,
          "sound": "default",
          "icon": "custom-icon",
          "category": "balance-update",
          "collapseKey": "balance-update",
          "validUntil": "2017-12-11T21:22:29.923Z",
          "extras": {
            "_comment": "Any custom data."
          }
        }
      }
    ]
  }
}
  • appId - Application that user is using.
  • mode - Mode of sending, default value is SYNCHRONOUS (response waits for all messages being sent), you can use ASYNCHRONOUS (return response immediately).
  • batch - List of messages, see documentation for sending a single message for details.

Response

{
  "status": "OK",
  "responseObject": {
    "mode": "SYNCHRONOUS",
    "result": {
      "ios": {
        "sent": 1,
        "pending": 0,
        "failed": 0,
        "total": 1
      },
      "android": {
        "sent": 1,
        "pending": 0,
        "failed": 0,
        "total": 1
      }
    }
  }
}
  • mode - Used sending mode.
  • result - Information about sending notifications. Present only for SYNCHRONOUS mode.
    • sent - Number of sent notifications.
    • failed - Number of failed notifications.
    • pending - Number of notifications that are still pending sending.
    • total - Number of total notifications.

Campaign

Used for informing closed group of users about some certain announcement containing message object described here.

Furthermore, the campaign comes with:

  • application that campaign is using
  • timestamp of
  • creation
  • sending
  • sent status - Whether is sent or not.
  • devices - To prevent getting multiple messages on device. If there would be more than one user registered.

post /push/campaign/create Create Campaign

Create a campaign with application that campaign is using and certain message that contains parameters of message object.

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "message": {
      "title": "Balance update",
      "titleLocKey": "balance.update.title",
      "titleLocArgs": [],
      "body": "Your balance is now $745.00",
      "bodyLocKey": "balance.update.body",
      "bodyLocArgs": [],
      "badge": 3,
      "sound": "default",
      "icon": "custom-icon",
      "category": "balance-update",
      "collapseKey": "balance-update",
      "validUntil": "2016-10-12T11:20:04Z",
      "extras": {
        "_comment": "Any custom data."
      }      
    }
  }
}
  • appId - Identifier of application that campaign is using.
  • message - parameters of message object are described here.

note: identifier of campaign is generated automatically

Response

{
  "status": "OK",
  "responseObject": {
    "id": "123456789012345678901234567890"
  }
}
  • id - Assigned ID to campaign.

delete /push/campaign/${id}/delete Delete Campaign

Delete a specific campaign. Also users associated with this campaign are going to be deleted. If deletion was applied then deleted status is true.

Query Parameters
id Campaign identifier
Request Body
{}
  • empty request body

Response

{
  "status": "OK",
  "responseObject" : {
    "deleted" : true
  }
}
  • deleted - Indicate if deletion was applied.

get /push/campaign/${id}/detail Get Campaign

Return details of a specific campaign.

Request

Query Parameters
id Campaign identifier

Response

{
  "status": "OK",
  "responseObject": {
    "id": "10",
    "appId": "mobile-app",
    "sent": "false",
    "message": {
      "title": "Balance update",
      "titleLocKey": "balance.update.title",
      "titleLocArgs": [],
      "body": "Your balance is now $745.00",
      "bodyLocKey": "balance.update.body",
      "bodyLocArgs": [],
      "badge": 3,
      "sound": "default",
      "icon": "custom-icon",
      "category": "balance-update",
      "collapseKey": "balance-update",
      "validUntil": "2016-10-12T11:20:04Z",
      "extras": {
        "_comment": "Any custom data."
      }
    }
  }
}
  • id - Identifier of campaign.
  • appId - Identifier of application that campaign is using.
  • sent - Indicator if campaign was sent.
  • message - parameters of message object are described here.

get /push/campaign/list Get List Of Campaigns

Return list of actually registered campaigns, based on all parameter. This parameter decides if return campaigns that are ‘only sent’(statement false) or return all registered campaigns (statement true).

Request

Response

{
  "status": "OK",
  "responseObject": [
    {
      "id": "10",
      "appId": "mobile-app",
      "sent": "false",
      "message": {
        "title": "Balance update",
        "titleLocKey": "balance.update.title",
        "titleLocArgs": [],
        "body": "Your balance is now $745.00",
        "bodyLocKey": "balance.update.body",
        "bodyLocArgs": [],
        "badge": 3,
        "sound": "default",
        "icon": "custom-icon",
        "category": "balance-update",
        "collapseKey": "balance-update",
        "validUntil": "2016-10-12T11:20:04Z",
        "extras": {
          "_comment": "Any custom data."
        }
      }
    }, {
      "id": "11",
      "appId": "mobile-app-other",
      "sent": "true",
      "message": {
        "title": "Balance update",
        "titleLocKey": "balance.update.title",
        "titleLocArgs": [],
        "body": "Your balance is now $300.00",
        "bodyLocKey": "balance.update.body",
        "bodyLocArgs": [],
        "badge": 3,
        "sound": "default",
        "icon": "custom-icon",
        "category": "balance-update",
        "collapseKey": "balance-update",
        "validUntil": "2017-10-12T11:20:04Z",
        "extras": {
          "_comment": "Any custom data."
        }
      }
    }
  ]
}
  • array of campaigns
  • id - Identifier of campaign.
  • appId - Identifier of application that campaign is using.
  • sent - Indicator if campaign was sent.
  • message - parameters of message object are described here.

put /push/campaign/${id}/user/add Add Users To Campaign

Associate users to a specific campaign. Users are identified in request body as an array of strings.

Request

Query Parameters
id Campaign identifier
Request Body
{
  "requestObject": [
    "1234567890",
    "1234567891",
    "1234567893"
  ]
}
  • list of users

Response

{
  "status": "OK"
}

get /push/campaign/${ID}/user/list Get Users From Campaign

Return list users from a specific campaign. Users are shown in paginated format based on parameters assigned in URI.

Request

Query Parameters
id Campaign identifier
page Number of page to show
size Number of elements per page

Response

{
  "status": "OK",
  "page": 0,
  "size": 4,
  "responseObject": {
    "campaignId": "1234",
    "users": [
      "1234567890",
      "1234567892",
      "1234567893"
    ]
  }
}
  • page - Actual page listed
  • size - Chosen number of users per page
  • campaignId - ID of a chosen campaign
  • users - Array of users based on pagination parameters

delete /push/campaign/${id}/user/delete Delete Users From Campaign

Delete users associated with a specific campaign. Users are identified request body as an array of strings.

Request

Query Parameters
id Campaign identifier 
{
  "requestObject": [
    "1234567890",
    "1234567891",
    "1234567893"
  ]
}
  • list of users

Response

{
  "status": "OK"
}

post /push/campaign/send/test/${id} Send Test Campaign Message

Send message from a specific campaign on test user to check rightness of that campaign.

Request

Query Parameters
id Campaign identifier
Request Body
{
  "requestObject": {
    "userId": "1234567890"
  }
}
  • userId - ID of test user, usually “1234567890”

Response

{
  "status": "OK"
}

post /push/campaign/send/live/${id} Send Campaign

Send message from a specific campaign to devices belonged to users associated with that campaign. Whereas each device gets a campaign only once.

If sending was successful then sent parameter is set on true and timestampSent is set on current time.

Request

Query Parameters
id Campaign identifier
  • empty request body

Response

{
  "status": "OK"
}

Administration

Services used for management of the push server instance.

get /admin/app/list List Applications

Get list of all applications.

Response

{
  "status": "OK",
  "responseObject": {
    "applicationList": [
      {
        "appId": "mobile-app",
        "ios": true,
        "android": true
      }
    ]
  }
}

get /admin/app/unconfigured/list List Unconfigured Applications

Get list of applications which have not been configured yet.

Response

{
  "status": "OK",
  "responseObject": {
    "applicationList": [
      {
        "appId": "mobile-app-other",
        "ios": null,
        "android": null
      }
    ]
  }
}

post /admin/app/detail Application Detail

Get detail of an application.

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "includeIos": true,
    "includeAndroid": true
  }
}

Response

{
  "status": "OK",
  "responseObject": {
    "application": {
      "appId": "mobile-app",
      "ios": true,
      "android": true
    },
    "iosBundle": "some.bundle.id",
    "iosKeyId": "KEYID123456",
    "iosTeamId": "TEAMID123456",
    "androidProjectId": "PROJECTID123"
  }
}

post /admin/app/create Create Application

Create a new supported application.

Request

{
  "requestObject": {
    "appId": "mobile-app"
  }
}

Response

{
  "status": "OK",
  "responseObject": {
    "appId": "mobile-app"
  }
}

put /admin/app/ios/update Update iOS Configuration

Update an iOS configuration.

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "bundle": "some.bundle.id",
    "keyId": "KEYID123456",
    "teamId": "TEAMID123456",
    "environment": null,
    "privateKeyBase64": "LS0tLS1CRUdJT..."
  }
}

You can use following environment values in request:

  • null - environment is decided by configuration of server property powerauth.push.service.apns.useDevelopment
  • development - use APNs development environment
  • production - use APNs production environment

Response

{
  "status": "OK"
}

delete /admin/app/ios/remove Remove iOS Configuration

Remove an iOS configuration.

Request

{
  "requestObject": {
    "appId": "mobile-app"
  }
}

Response

{
  "status": "OK"
}

put /admin/app/android/update Update Android Configuration

Update an Android configuration.

Request

{
  "requestObject": {
    "appId": "mobile-app",
    "projectId": "PROJECTID123",
    "privateKeyBase64": "ewogICJ0eXBlIjog..."
  }
}

Response

{
  "status": "OK"
}

delete /admin/app/android/remove Remove Android Configuration

Remove FCM configuration for Android push messages.

Request

{
  "requestObject": {
    "appId": "mobile-app"
  }
}

Response

{
  "status": "OK"
}

Message Inbox

When communicating with your users, you can use the message inbox to store messages for users. Inbox is not responsible for sending push notifications, but it is responsible for handling messages that should be read by the user later and for marking the messages as read, while marking a timestamp.

Each message can have associated a type - either text, or html:

  • For text messages, the layout of the final message is defined by subject and body attributes. The summary attribute is only used in list and push notifications.
  • For html messages, the subject and summary attributes are only used in list and push notifications, the body attribute contains the full formatted HTML document.

To notify the user about a new message in the inbox, call the POST /message/send (or other push message sending API) right after you post a message in the inbox.

post /inbox/messages Post Message to Inbox

Post provided message to an inbox of a given user.

Request

Request Body
{
  "requestObject": {
    "userId": "user-001",
    "type": "text",
    "subject": "Example subject",
    "summary": "Example summary",
    "body": "Example message body",
    "applications": [
      "application-001",
      "application-002"
    ]
  }
}

Response

{
  "status": "OK",
  "responseObject": {
    "id": "ae641389-d37a-4425-bd14-41c29484596f",
    "userId": "user-001",
    "type": "text",
    "subject": "Example subject",
    "summary": "Example summary",
    "body": "Example message body",
    "read": false,
    "timestampCreated": "2022-08-25T22:34:58.702+00:00",
    "applications": [
      "application-001",
      "application-002"
    ]
  }
}

get /inbox/messages/list Get User Messages

Get messages from an inbox of a given user.

Request

Query Params
userId User ID
applications Applications, comma-separated value of application IDs.
onlyUnread Set to true to return only unread messages.
page Page index, zero based. Default: 0.
size Page size. Default: 100.

Response

{
  "status": "OK",
  "page": 0,
  "size": 20,
  "responseObject": [
    {
      "id": "059b3a83-c025-45be-b815-497d39222024",
      "type": "text",
      "subject": "Hello, how are you?",
      "summary": "Example summary",
      "read": true,
      "timestampCreated": "2022-08-25T20:35:01.067+00:00"
    },
    {
      "id": "ae641389-d37a-4425-bd14-41c29484596f",
      "type": "text",
      "subject": "Example subject",
      "summary": "Example summary",
      "read": false,
      "timestampCreated": "2022-08-25T22:34:58.702+00:00"
    }
  ]
}

get /inbox/messages/count Get Count of Unread Messages

Get number of unread messages in an inbox of a given user.

Request

Query Params
userId User ID
appId Application ID

Response

{
  "status": "OK",
  "responseObject": {
    "countUnread": 1
  }
}

get /inbox/messages/detail Get Message Detail by ID

Get full message detail from an inbox for a given message ID.

Request

Query Params
messageId Message ID

Response

{
  "status": "OK",
  "responseObject": {
    "id": "ae641389-d37a-4425-bd14-41c29484596f",
    "userId": "user-001",
    "type": "text",
    "subject": "Example subject",
    "summary": "Example summary",
    "body": "Example message body",
    "read": false,
    "timestampCreated": "2022-08-25T22:34:58.702+00:00",
    "applications": [
      "application-001",
      "application-002"
    ]
  }
}

put /inbox/messages/read Mark Message as Read

Mark a message in an inbox as read. In case the message is already read, this call is a no-op.

Request

Query Params
userId User ID
messageId Message ID

Response

{
  "status": "OK",
  "responseObject": {
    "id": "ae641389-d37a-4425-bd14-41c29484596f",
    "userId": "user-001",
    "type": "text",
    "subject": "Example subject",
    "summary": "Example summary",
    "body": "Example message body",
    "read": true,
    "timestampCreated": "2022-08-25T22:34:58.702+00:00",
    "applications": [
      "application-001",
      "application-002"
    ]
  }
}

put /inbox/messages/read-all Mark All Unread Messages as Read for User

Mark all unread messages in an inbox of a given user as read.

Request

Query Params
userId User ID
appId Application ID

Response

{
  "status": "OK"
}
Last updated on Mar 16, 2023 (11:35) Edit on Github Send Feedback
Search

1.6.x

PowerAuth Push Server