Contents

Documentation

Messaging API

This document will describe the main technical characteristics to integrate the PassByME Messaging service.

Overview

The Message API is a low-level, REST API for developers to integrate to the PassByME platform. Messaging has three different methods to send messages to smartphone devices that has the PassByME application ready and installed.

Authorization messages for adding strong two-factor authentication to your website or application.
General messages to send simple text messages to registered PassByME users.
eSign messages to sign documents with your mobile device. If you interested in eSign solution, please contact us on email.
 

First Step

You'll need a PassByME account, and a certificate to access the messaging API from your application. Sign Up using the web-based administration interface, and register a new organization if you haven’t registered before. If you have already registered into the PassByME service, please log in as an administrator with your previously created credential data (username/password and your PassByME ready mobile device).

To access the PassByME service URL you should have a valid authentication certificate and key (PFX file): The PassByME management service URL can be used only with a valid authentication certificate, which you can acquire after the registration process.

Download PFX:

Log into your administration page.
Select the "Access Keys" menu.
Create an application by clicking on the "Add access key" button.
Choose "Application key" as access key type and choose a name for the new access key".
Click your newly created application icon.
Choose "Download PFX" option.

This certificate has a software-based private key inside the downloaded PFX. The PFX file is protected with a passphrase, which can be printed on the administration website. Note that the certificate can be downloaded in PEM format as well.

Important! The authentication certificate identifies the registered APPLICATION in the PassByME service.

This API is available for FREE up to 10 users!

Check out PassByME REST API client libraries and sample source code for Java, C#, Node.js and PHP.

 

Message Delivery

Sending Message

Sends a message to the smartphones of the given users.
post
/messages

Parameters

json
in request body.
FieldMandatoryDescription
recipientsRequired

A JSON Array of PassByME IDs.

FieldMandatoryDescription
Optional

Optional

subjectRequired

A string that contains the message subject. Maximum size is 254 characters.

bodyRequired

A string that contains the message body. Maximum size is 16376 characters.

previewOptional

A string that contains the message preview. Maximum size is 300 characters.

availabilityRequired

An integer that denotes the availability of the message in seconds.

typeRequired

Message type: "authorization", "message", "esign" or "oneTimePassword".

callbackUrlOptional

Only available when PassByME is deployed on premise. Contact sales@passbyme.com for on premise offers

A string that contains a callback url used for recipient status reporting. Maximum size is 254 characters. Method: POST Request body: tracking info in JSON format. See Output

minimumTrustLevelOptional

This level defines the trustiness of the certificate required to upload the evidence of the message :"any", "advanced" or "qualified" (optional, default: "any").

organizationOptional

Only available when the sender organization has right to do that.

The recipient organization OID where the recipients should be searched for. This organization will be used for push credentials as well (optional, available only if the sender organization has rights to do so)

checkSecureIdOptional

A boolean flag to force that the user must validate secureId on the device (optional, default: false).

secureIdOptional

The secureId of the message can be set by the sender (optional, default: server-side generated random value).

externalIdOptional

The unique part of the message id can be set by the sender (optional, default: server-side generated random value).

documentsOptional

A JSON Array of documents to attach

FieldMandatoryDescription
documentNameRequired

The document name

downloadUrlRequired

Download URL

downloadUrlExpiryRequired

The expiration date of the download URL

Request example

/messages
{"recipients":[{}],"subject":"Example message subject","body":"The body of your message.","preview":"The preview of your message.","availability":300,"type":"authorization","callbackUrl":"www.report.sales.passbyme.com","minimumTrustLevel":"any","organization":"1.2.3.4.5.6","checkSecureId":"false","secureId":"abc123","externalId":"fZFbDOsv","documents":[{"documentName":"Example file name","downloadUrl":"https://any.hu/any.doc","downloadUrlExpiry":"2020-04-01T20:00:00Z"}]}

Success response format

FieldTypeDescription
messageIdString

Identifier of the sent message.

expirationDateString (ISO 8601)

The expiry date of the current message.

recipientsArray

A list of recipients and their status information.

FieldTypeDescription
userIdString

The user identifier.

statusString

The status of the message.

Success response

HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}]}
 

Tracking Message

Returns the status of a message, identified by the given messageId.
get
/messages/:messageId

Parameters

query string
FieldMandatoryDescription
messageIdRequired

The identifier of the message to be tracked.

Request example

/messages/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv

Success response format

FieldTypeDescription
messageIdString

Identifier of the sent message.

expirationDateString (ISO 8601)

The expiry datetime of the current message.

recipientsArray

A list of recipients and their status information.

FieldTypeDescription
userIdString

The user identifier.

statusString

The status of the message.

secureIdString

The session identifier of the message. This id shows up in the mobile device after receiving an authentication message.

Success response

HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}],"secureId":"N7voX4"}
 

Cancelling Message

Cancels a message, identified by the given messageId.
delete
/messages/:messageId

Parameters

query string
FieldMandatoryDescription
messageIdRequired

The identifier of the message.

Request example

/messages/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv

Success response format

FieldTypeDescription
messageIdString

Identifier of the sent message.

expirationDateString (ISO 8601)

The expiry datetime of the current message.

recipientsArray

A list of recipients and their status information.

FieldTypeDescription
userIdString

The user identifier.

statusString

The status of the message.

secureIdString

The session identifier of the message. This id shows up in the mobile device after receiving an authentication message.

Success response

HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}],"secureId":"N7voX4"}
 

ConfigurationUpdate Message

Cancels a message, identified by the given messageId.
post
/messages/configurationUpdate

Parameters

json
in request body.
FieldMandatoryDescription
vendorIdRequired

Identifier of the selected user's device.

subjectRequired

A string that contains the message subject. Maximum size is 254 characters.

bodyRequired

Contains a ConfigUpdateBody.

FieldMandatoryDescription
Optional

Optional

previewOptional

A string that contains the message preview. Maximum size is 300 characters.

availabilityRequired

An integer that denotes the availability of the message in seconds.

externalIdOptional

The unique part of the message id can be set by the sender (optional, default: server-side generated random value).

Request example

/messages/configurationUpdate
{"vendorId":"0ecgjX4cCBkDLe2EokMnlP6jjII=","subject":"Example message subject","body":[{}],"preview":"The preview of your message.","availability":300,"externalId":"fZFbDOsv"}

Success response format

FieldTypeDescription
messageIdString

Identifier of the sent message.

expirationDateString (ISO 8601)

The expiry datetime of the current message.

recipientsArray

A list of recipients and their status information.

FieldTypeDescription
userIdString

The user identifier.

statusString

The status of the message.

secureIdString

The session identifier of the message. This id shows up in the mobile device after receiving an authentication message.

Success response

HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"0ecgjX4cCBkDLe2EokMnlP6jjII=","status":"PENDING"}],"secureId":"N7voX4"}
 

Broadcast Message

Sends a message to every user in the current organization.
post
/messages/broadcast

Parameters

json
in request body.
FieldMandatoryDescription
subjectRequired

A string that contains the message subject. Maximum size is 254 characters.

bodyRequired

A string that contains the message body. Maximum size is 16376 characters.

previewOptional

A string that contains the message preview. Maximum size is 300 characters.

availabilityRequired

An integer that denotes the availability of the message in seconds.

typeRequired

Message type: "authorization", "message", "esign" or "oneTimePassword".

callbackUrlOptional

Only available when PassByME is deployed on premise. Contact sales@passbyme.com for on premise offers

A string that contains a callback url used for recipient status reporting. Maximum size is 254 characters. Method: POST Request body: tracking info in JSON format. See Output

minimumTrustLevelOptional

This level defines the trustiness of the certificate required to upload the evidence of the message :"any", "advanced" or "qualified" (optional, default: "any").

organizationOptional

Only available when the sender organization has right to do that.

The recipient organization OID from which the recipients will be addressed.

checkSecureIdOptional

A boolean flag to force that the user must validate secureId on the device (optional, default: false).

secureIdOptional

The secureId of the message can be set by the sender (optional, default: server-side generated random value).

externalIdOptional

The unique part of the message id can be set by the sender (optional, default: server-side generated random value).

documentsOptional

A JSON Array of documents to attach

FieldMandatoryDescription
documentNameRequired

The document name

downloadUrlRequired

Download URL

downloadUrlExpiryRequired

The expiration date of download URL

Request example

/messages/broadcast
{"subject":"Example message subject","body":"The body of your message.","preview":"The preview of your message.","availability":300,"type":"authorization","callbackUrl":"www.report.sales.passbyme.com","minimumTrustLevel":"any","organization":"1.2.3.4.5.6","checkSecureId":"false","secureId":"abc123","externalId":"fZFbDOsv","documents":[{"documentName":"Example file name","downloadUrl":"https://any.hu/any.doc","downloadUrlExpiry":"2020-04-01T20:00:00Z"}]}

Success response format

FieldTypeDescription
messageIdString

Identifier of the sent message.

expirationDateString (ISO 8601)

The expiry datetime of the current message.

recipientsArray

A list of recipients and their status information.

FieldTypeDescription
userIdString

The user identifier.

statusString

The status of the message.

Success response

HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}]}
 

Renotify recipients

Returns the status of the message after renotification, identified by the given messageId.
post
/messages/:messageId/renotify

Parameters

query string
FieldMandatoryDescription
messageIdRequired

The identifier of the message for which the renotifications will be send

Request example

/messages/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv/renotify

Success response format

FieldTypeDescription
messageIdString

Identifier of the sent message.

expirationDateString (ISO 8601)

The expiry datetime of the current message.

recipientsArray

A list of recipients and their status information.

FieldTypeDescription
userIdString

The user identifier.

statusString

The status of the message.

secureIdString

The session identifier of the message. This id shows up in the mobile device after receiving an authentication message.

Success response

HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","expirationDate":"2016-08-16T12:49:03.833Z","recipients":[{"userId":"john.doe@passbyme.com","status":"PENDING"}],"secureId":"N7voX4"}
 

Identification

Start identification

Start an identification process.
post
/identification

Parameters

json
in request body.
FieldMandatoryDescription
subjectRequired

A string that contains the identification message subject. Maximum size is 254 characters.

bodyRequired

A string that contains the identification message body. Maximum size is 16376 characters.

previewOptional

A string that contains the message preview. Maximum size is 300 characters.

availabilityRequired

An integer that denotes the availability of the identification message in seconds.

callbackUrlOptional

Only available when PassByME is deployed on premise. Contact sales@passbyme.com for on premise offers

A string that contains a callback url used for recipient status reporting. Maximum size is 254 characters. Method: POST Request body: tracking info in JSON format. See Output

minimumTrustLevelOptional

This level defines the trustiness of the certificate required to upload the evidence of the message :"any", "advanced" or "qualified" (optional, default: "any").

externalIdOptional

The unique part of the message id can be set by the sender (optional, default: server-side generated random value).

Request example

/identification
{"subject":"Example message subject","body":"The body of your message.","preview":"The preview of your message.","availability":300,"callbackUrl":"www.report.sales.passbyme.com","minimumTrustLevel":"any","externalId":"LsdyqjBQ"}

Success response format

FieldTypeDescription
messageIdString

Identifier of the sent identification message.

qrContentString

This content should be presented in a QR code for the user to be identified.

expirationDateString (ISO 8601)

The expiry date of the current identification message.

Success response

HTTP/1.0 200 OK
{"messageId":"@pbmdevcore1-1.3.6.1.4.1.21528.3.3.2.1.121376.2.122416-LsdyqjBQ","qrContent":"pbmid:@pbmdevcore1-1.3.6.1.4.1.21528.3.3.2.1.121376.2.122416-LsdyqjBQ","expirationDate":"2018-05-25T13:29:46.820Z"}
 

Tracking Identification Message

Returns the identifier of the customer, who has adopted the identification message, identified by the given messageId.
Before a valid identification it is returning a HTTP 204 response (No content) with empty body.
get
/identification/:messageId

Parameters

query string
FieldMandatoryDescription
messageIdRequired

The identifier of the identification message to be tracked.

Request example

/identification/@pbmdevcore1-1.3.6.1.4.1.21528.3.3.2.1.121376.2.122416-LsdyqjBQ

Success response format

FieldTypeDescription
IDString

Unique OID of the identified customer identity.

Success response

HTTP/1.0 200 OK
{"ID":"1.3.6.1.4.1.21528.3.3.2.1.121376.2.126602"}
 

Evidences API

Download evidence

Download an evidence knowing the corresponding messageId, recipientId and evidenceId.
get
/download/messages/:messageId/recipients/:recipientId/evidences/:evidenceId

Parameters

query string
FieldMandatoryDescription
messageIdRequired

The identifier of the message belonging to the actual evidence.

recipientIdRequired

The identifier of the recipient who uploaded the evidence.

evidenceIdRequired

The identifier of the evidence to be downloaded.

Request example

/download/messages/@pbm1-1.3.6.1.4.1.21528.3.3.2.1.2.122416-LTggLGHV/recipients/1.3.6.1.4.1.21528.3.3.2.1.1.121377/evidences/410196

Success response format

FieldTypeDescription
P7S

The downloadable evidence in p7s (pkcs7 signature) format.

Success response

HTTP/1.0 200 OK
"<P7S bytes>"
 

Download evidence

Download an evidence knowing the corresponding messageId, recipientId and evidence type.
get
/download/messages/:messageId/recipients/:recipientId/evidencetype/:evidenceType

Parameters

query string
FieldMandatoryDescription
messageIdRequired

The identifier of the message belonging to the actual evidence.

recipientIdRequired

The identifier of the recipient who uploaded the evidence.

evidenceTypeRequired

The identifier of the evidence type to be downloaded: "pod" (proof of delivery) or "st" (signed transaction).

Request example

/download/messages/@pbm1-1.3.6.1.4.1.21528.3.3.2.1.2.122416-LTggLGHV/recipients/1.3.6.1.4.1.21528.3.3.2.1.1.121377/evidencetype/pod

Success response format

FieldTypeDescription
P7S

The downloadable evidence in p7s (pkcs7 signature) format.

Success response

HTTP/1.0 200 OK
"<P7S bytes>"
 

Download evidence by evidenceId

Download an evidence by its id.
get
/download/evidences/:evidenceId

Parameters

query string
FieldMandatoryDescription
evidenceIdRequired

The identifier of the evidence to be downloaded.

Request example

/download/evidences/410196

Success response format

FieldTypeDescription
P7S

The downloadable evidence in p7s (pkcs7 signature) format.

Success response

HTTP/1.0 200 OK
"<P7S bytes>"
 

Download message details

Download detailed information of the specified message.
get
/download/messages/:messageId

Parameters

query string
FieldMandatoryDescription
messageIdOptional

Identifier of the sent message.

Request example

/download/messages/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv

Success response format

FieldTypeDescription
messageIdString

Identifier of the sent message.

submitDateString (ISO 8601)

The datetime of submitting the message.

subjectString

A string that contains the sent message subject

senderApplicationNameString

A string that contains the sent message subject

senderApplicationIdString

A id of the sender application

expirationString (ISO 8601)

The expiry datetime of the current message.

messageTypeString ("message", "esign", "authorization", "oneTimePassword", "configurationUpdate" or "identification")

The type of the message.

recipientsArray

A list of recipients and their status information.

FieldTypeDescription
userIdString

The user identifier.

oidString

The oid of the user.

statusString

The status of the message.

lastUpdateDateString (ISO 8601)

The datetime of last modification.

evidencesArray

A list of evidences and their status information.

{
status : String ("PENDING", "VALID", "INVALID" or "FATAL")
deviceName : String
submitDate : String (ISO 8601)
evidenceType : String ("SIGNED_TRANSACTION" or "PROOF_OF_DELIVERY")
evidenceUrl : String
attachment : String
format : String ("CONCATENATED" or "JSON")
}

Success response

HTTP/1.0 200 OK
{"messageId":"@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv","submitDate":"2016-08-16T11:49:03.833Z","subject":"subject","senderApplicationName":"TestApplication","senderApplicationId":"1.3.6.1.4.1.21528.3.3.2.1.121376.2.122416","expiration":"2016-08-16T12:49:03.833Z","messageType":"message","recipients":[{"userId":"john.doe@passbyme.com","oid":"1.3.6.1.4.1.21528.3.3.2.1.121376.1.121377","status":"PENDING","lastUpdateDate":"2016-08-16T11:55:03.833Z","evidences":[{"status":"PENDING","deviceName":"Vendor F12G","submitDate":"2016-08-16T11:55:03.833Z","evidenceType":"PROOF_OF_DELIVERY","evidenceUrl":"https://admin.passbyme.com/register/rest/download/messagehistory/@pbmcore1-1.3.6.1.4.1.21528.3.3.2.9045.2.10111-fZFbDOsv/recipients/1.3.6.1.4.1.21528.3.3.2.1.121376.1.121377/evidenceType/pod","attachment":"PROOF_OF_DELIVERY","format":"JSON"}]}]}
 

Status Codes

Messages has the following valid status codes.

Status CodeDescription
PENDING

Initial status of the message.

NOTIFIED

The recipient has been notified about a new message.

DOWNLOADED

The recipient has downloaded the message, but has not uploaded the evidence yet.

SEEN

The recipient has seen the message and uploaded the evidence.

NOT_SEEN

The recipient has not seen the message.

NOT_NOTIFIED

The recipient has not received the notification.

NOT_DOWNLOADED

The recipient received the notification about the message but has not downloaded the message.

NO_DEVICE

The message could not be sent because the recipient had no PassByME ready device that supports messaging.

FAILED

The message could not be sent because of an error.

DISABLED

The message could not be sent because the recipient is disabled.

CANCELLED

The message was cancelled by the sender.

APPROVED

Authentication has finished successfully.

DENIED

The user has cancelled the authentication.