Select release
On this page:

Push Server API

Edit on Github Send Feedback v1.3.0

Push Server provides a simple to use 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": 2,
    "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": 2,
    "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": 2,
    "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": 2,
    "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.
  • 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"
}

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

Sends a message 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": 2,
    "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."
          }
        }
      }
    ]
  }
}

Response

{
  "status": "OK",
  "responseObject": {
    "result": {
      "ios": {
        "sent": 1,
        "pending": 0,
        "failed": 0,
        "total": 1
      },
      "android": {
        "sent": 1,
        "pending": 0,
        "failed": 0,
        "total": 1
      }
    }
  }
}
  • result - Information about sending notifications.
  • sent - Number of sent notifications.
  • failed - Number of failed notifications.
  • total - Number of total notifications.

Campaign

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

Further 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": "2",
    "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": 2,
    "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": 2,
      "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": 3,
      "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": [
      {
        "id": 1,
        "appId": 1,
        "appName": "app1",
        "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": [
      {
        "id": 2,
        "appId": null,
        "appName": "app2",
        "ios": null,
        "android": null
      }
    ]
  }
}

post /admin/app/detail Application Detail

Get detail of an application.

Request

{
  "requestObject": {
    "id": 1,
    "includeIos": true,
    "includeAndroid": true
  }
}

Response

{
  "status": "OK",
  "responseObject": {
    "application": {
      "id": 1,
      "appId": 1,
      "appName": "app1",
      "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": 4
  }
}

Response

{
  "status": "OK",
  "responseObject": {
    "id": 5
  }
}

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

Update an iOS configuration.

Request

{
  "requestObject": {
    "id": 1,
    "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": {
    "id": 5
  }
}

Response

{
  "status": "OK"
}

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

Update an Android configuration.

Request

{
  "requestObject": {
    "id": 5,
    "projectId": "PROJECTID123",
    "privateKeyBase64": "ewogICJ0eXBlIjog..."
  }
}

Response

{
  "status": "OK"
}

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

Remove FCM configuration for Android push messages.

Request

{
  "requestObject": {
    "id": 5
  }
}

Response

{
  "status": "OK"
}
Last updated on Jan 26, 2022 (17:29) Edit on Github Send Feedback
Search

1.3.x

PowerAuth Push Server