Skip to content

Push Server API

Jump to bottom
Petr Dvorak edited this page Mar 14, 2017 · 26 revisions

Push Server provides a simple to use RESTful API for the 3rd party integration purposes. The API contains methods for device registration, device blocking, sending single or batch messages and service cleanup.

Following endpoints are published in PowerAuth 2.0 Push Server RESTful API:

Error handling

PowerAuth 2.0 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:

Code Description
200 OK response, no issues
400 Issue with a request format, or issue of the business logic
401 Unauthorized, invalid security token configuration

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

{
	"status": "ERROR",
	"responseObject": {
		"code": "ERROR_CODE",
		"message": "ERROR_MESSAGE_IN_ENGLISH"
	}
}

Register new device

This end-point registers a new device push token (platform specific). Optionally, the call may include also activationId, so that the token is associated with given user in the PowerAuth 2.0 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 activationId value, so that there are no incorrect bindings.

Method POST
Resource URI /push/device/create

Request

  • Headers:
    • Content-Type: application/json
{
	"appId": 2,
    "token": "1234567890987654321234567890",
    "platform": "ios",
    "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412"
}

Note: Activation ID is optional.

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
    "status": "OK"
}

Update registration status

Update the status of given registration based on the associated activation status. This endpoint can help assure that registrations whose associated PowerAuth 2.0 activations are in non-active state cannot receive personal messages.

Method POST
Resource URI /push/device/status/update

Request

  • Headers:
    • Content-Type: application/json
{
    "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412",
    "status": "BLOCKED"
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
    "status": "OK"
}

Remove device registration

Removes registered device based on the push token value.

Method POST
Resource URI /push/device/remove

Request

  • Headers:
    • Content-Type: application/json
{
	"appId": 2,
    "token": "12456789098321234567890"
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
    "status": "OK"
}

Send a single message

Sends a single push message to given user via provided application (optionally to the specific device represented by given activationId).

Method POST
Resource URI /push/message/send

Request

  • Headers:
    • Content-Type: application/json
{
	"appId": 2,
	"push": {
	    "userId": "123",
	    "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412",
	    "silent": true,
	    "personal": true,
	    "encrypted": false,
	    "message": {
	        "title": "Balance update",
	        "body": "Your balance is now $745.00",
	        "badge": 3,
	        "sound": "riff.wav",
	        "category": "balance-update",
			"collapseKey": "balance-update",
	        "validUntil": "2016-10-12T11:20:04Z",
	        "extras": {
	            "_comment": "Any custom data."
	        }
	    }
	}
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
    "status": "OK"
}

Send a message batch

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

Method POST
Resource URI /push/message/batch/send

Request

  • Headers:
    • Content-Type: application/json
{
	"app_id": 2,
    "batch": [
		{
		    "userId": "123",
		    "activationId": "49414e31-f3df-4cea-87e6-f214ca3b8412",
		    "silent": true,
		    "personal": true,
		    "encrypted": false,
		    "message": {
		        "title": "Balance update",
		        "body": "Your balance is now $745.00",
		        "badge": 3,
		        "sound": "riff.wav",
		        "category": "balance-update",
				"collapseKey": "balance-update",
		        "validUntil": "2016-10-12T11:20:04Z",
		        "extras": {
		            "_comment": "Any custom data."
		        }
		    }
		}
    ]
}

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
    "status": "OK",
    "result": {
		"ios": {
			"sent": "1",
			"failed": "0",
			"total": "1"
		},
		"android": {
			"sent": "1",
			"failed": "0",
			"total": "1"
		}
	}
}

Hello Endpoint

Sends a basic ping to the endpoint.

Method GET
Resource URI /push/service/hello

Request

  • Headers:
    • Content-Type: application/json

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
    "status": "OK"
}

System Status Endpoint

Sends a system status request, with basic information about the running app.

Method GET
Resource URI /push/service/status

Request

  • Headers:
    • Content-Type: application/json

Response

  • Status Code: 200
  • Headers:
    • Content-Type: application/json
{
    "status" : "OK",
    "applicationName" : "powerauth-push",
    "applicationDisplayName" : "PowerAuth 2.0 Push Server",
    "applicationEnvironment" : "",
    "timestamp" : "2017-03-14T14:54:14Z"
}

Deployment Tutorials

Integration Tutorials

Reference Manual

Technical Topics

Clone this wiki locally