NAV Navbar
Logo
PHP

Introduction

Content-type: application/json
Method: POST

The PushAuth API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

Security

HMAC algorithm: SHA-256
HMAC data: base64(json)
HMAC password: private key
HMAC result type: base64(bytes)

Data from your server to the PushAuth server is transmitted in a closed form, via TLS, using the HMAC signature with SHA-256.

Take care of the secure storage of your Private Key.

All requests contains variables:

Type Param Description
string pk Your application public key
string data JSON-encoded string in BASE64 with signature

data is string, for example: qwerty.zxcvb, where:

qwerty - json encoded string in BASE64

zxcvb - HMAC hash of qwerty, in BASE64, with your private key.

And we explain, how to generate data string for requests and how to check server response.

Encoding data

<?php
//Setting data params
$data = json_encode(['addr_to'     => 'client@mysite.com',
                     'mode'           => 'push'
                     ]);

//Try encode data
$encodedData = base64_encode($data);
$signature = base64_encode(hash_hmac('sha256',$encodedData,'myPrivateKey',true));

//Encoded data
$requestString = $encodedData. '.' .$signature;

Result:

"eyJhZGRyZXNzX3RvIjoiY2xpZW50QG15c2l0ZS5jb20iLCJtb2RlIjoicHVzaCJ9.2MshIWdAZ1K8vvau+e9JdBOEgHTwoqNhUiRQY6A/QBE="

Image of Security

After successfully registering the application in the dashboard, you have a private key available. You will use it to sign data using HMAC (SHA-256).

Actions

  1. An encoded string consists of two string values, which are separated by a dot. (Example: jsonDataInBase64.hmacInBase64).
  2. Get the first part, encode your json data in BASE64.
  3. Generate the second part, create the HMAC using the value (string) from the first part with your private key and the SHA256 algorithm. For example, hash_hmac('sha256', data, private_key). And the received data must be encoded in BASE64.
  4. As a result, you have two values, separated by dot.

Decoding data

<?php
//Response JSON
$inputJson="'message':'Success push created!','data':'YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd29OakpvYmFk.ajZTYjdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq'";

//Convert to Array
$inputArr=json_decode($inputJson,true);

$data = $inputArr['data'];
$dataArray = explode('.', $data);

//Fetch data
$clearData = $data[0];
$dataString = base64_decode($data[0]);

//Fetch signature
$serverSignature = $data[1];

//Generate your signature
$clientSignature = base64_encode(hash_hmac('sha256',$clearData,'PrivateKey', true));

//Check your signature with Server signature
if ($serverSignature != $clientSignature ) {
         throw new \Exception('Signature incorrect!');
}

$result = json_decode($dataString,true);

Result:

["req_hash"=>"someUniqCodeHash",
"answer"=>true]

Algorithm for decoding a string

We have a private key. The order of actions:

  1. We have encoded string, example: YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd29OakpvYmFkajZTY.jdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq
  2. We split the line using the dot separator symbol into two lines. The first part of it will be data, and second - HMAC-signature. At result, data: YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd29OakpvYmFkajZTY and signature: jdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq
  3. Decode data by Base64 function. And we receive json.
  4. To verify the validity of the data, we generate HMAC signature. To do this, we use the data encoded in base64 (example: YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd29OakpvYmFkajZTY), algorithm SHA-256 and private key. And the result encode in base64.
  5. Now we need to compare: our generated HMAC and HMAC, obtained from the answer. If they coincide, then you can trust the answer.

Push request

Request

{
"pk":"56a24f5f9ee389dd88e4e071ce7fe67a",
"data":"YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd29OakpvYmFkaj.ZTYjdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq"
}

Decoded data parameter:

{
"addr_to":"client@yoursite.com",
"mode":"code",
"code":"123-456"
}

Parameter address_to can be json array like this:

{
"addr_to":{
    '1':'client1@example.com',
    '2':'client2@example.com',
    '3':'client3@example.com'
            },
"mode":"push"
}

or this for one client:

{
"addr_to":{
    '1':'client1@example.com'
            },
"mode":"push"
}

or this for random client:

{
"addr_to":{
    '3':'client1@example.com',
    '1':'client2@example.com',
    '2':'client3@example.com'
            },
"mode":"push"
}

Sending PUSH-request for your client

This request allows you to send a push request, using PushAuth, to your client, knowing it email-address, to mobile device and receive response. Your client must have installed mobile iOS or Android app with logged email

HTTP request

POST https://api.pushauth.io/push/send

Content-Type: application/json

Query parameters

Type Param Description
string pk Your application public key
string data JSON-encoded string, with key/values.
string/json addr_to E-mail address of client device app.
string mode Mode of push request. Available: push - push request with question (yes or no) or code - for sending code value.
string(8) code Code/text/char or …, that be displayed at client device application, only if selected mode = code
boolean flash_response Mode of server response. If true - then immediately, after sending a push request, you will receive a response with a request hash that you can then check the status of the response from your client (his device). If false - then after sending a push request, the server will wait for a response from your client (his device) within 30 seconds. If the answer is not received, during this time - you will receive a response from the server.

Response

{
"message":"Success push created!",
"data":"YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd29OakpvYm.FkajZTYjdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq"
}

Decoded data parameter:

{
"req_hash":"someUniqCodeHash",
"answer":true
}

The response from the server will be with the code 200 if the push is successful, otherwise see the error codes.

Content-Type: application/json

Response Code: 200 OK

Type Param Description
string message Message with error description.
string data JSON-encoded data, with key/values.
string req_hash A unique request hash, through which you can check the status of the authorization request
boolean answer Client answer. true - if clicked yes, false - if clicked no.

Auth by QR-code

Request

{
"pk":"56a24f5f9ee389dd88e4e071ce7fe67a",
"data":"YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd29OakpvYmFkaj.ZTYjdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq"
}

Decoded data parameter:

{
"image":{
    "size":"128",
    "color":"40,0,40",
    "backgroundColor":"255,255,255",
    "margin":"1"
         }
}

You can use QR-code auth in your application. You show only QR-code and your client scan it by PushAuth mobile Application, and you can identify client.

This request allows you to get Request Hash, for check autorization status and QR-code URL image for showing on your application.

Method: POST

API Endpoint: https://api.pushauth.io/qr/show

Content-Type: application/json

Type Param Description
json array image All available parameters for image customize
string or integer size Image size in px.
string color Image color in RGB.
string backgroundColor Image background color in RGB.
string or integer margin QR margin at image (1..10)

Response

{
"data":"YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd.29OakpvYmFkajZTYjdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq"
}

Decoded data parameter:

{
"req_hash":"12345678901234567890123456789012",
"qr_url":"https://api.pushauth.io/qr/show/image/somelongstringinbase64"
}

The response show Request Hash and URL to QR code image.

Content-Type: application/json

Response Code: 200 OK

Type Param Description
string req_hash Request hash for check state.
string qr_url URL to QR-image.

Check request status

Request

{
"pk":"56a24f5f9ee389dd88e4e071ce7fe67a",
"data":"YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd29Oak.pvYmFkajZTYjdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq"
}

Decoded data parameter:

{
"req_hash":"someUniqReqHash"
}

After the successful push request for authorization has been successfully sent, you can request the status of the authorization request using the previously obtained authorization request hash.

Method: POST

API Endpoint: https://api.pushauth.io/push/status

Content-Type: application/json

Type Param Description
string pk Your application public key.
string data JSON-encoded data.
string req_hash A unique authorization request hash, through which you can check the status of the authorization request.

Response

{
"data":"YlRyencwNUU0b2NvTXFPUTl5alhheXlpZnhoTVNqZFhSVWJYd.29OakpvYmFkajZTYjdTejdOR2Vicnp4dDN2WC51MoZQEoQAwnbw2RGb6Dvq"
}

Decoded data parameter:

{
"answered":true,
"answer":true,
"response_code":200,
"response_message":"Ok message!",
"response_dt":1234567
}

The response from the server will be with the code 200 if the request is processed successfully, otherwise - see the error code.

Content-Type: application/json

Response Code: 200 OK

Type Param Description
string data Encoded data string
boolean answered Status of client device response, true- if response exists, false - if not exists.
boolean answer Response answer, true - if client clicked yes, false - if clicked no.
integer response_code Code of response
string response_message Response message
integer response_dt Date and time of client response. format UNIX_TIMESTAMP in UTC.

Errors

This section describes the basic error codes for response. If the code is 4xx or 5xx, then most likely there will be json values: status_code and message.

Code Description
200 OK Successfully processed request
403 Access Denied Access is denied, the user or device may be locked
404 Not Found Not found
405 Method Not Allowed The request was not sent by that method (POST/GET/PATCH/DELETE)
422 Unprocessable Entity Error in request parameter
500 Internal Server Error Error in server side

Web-hooks

You can use Web hooks service. After client actions on mobile app, we send POST request to your server.

Content-Type: application/json

or

Content-Type: application/x-www-form-urlencoded

Method: POST

Your server response code must be 200.

QR-code

[hook] => Array
        (
            [event] => client_read_qrcode
            [timestamp] => 1500670315
            [data] => eyJyZXFfaGFzaCI6InRlc3QtZGF0YSIsImFwcF9wdWJsaWNfa2V5IjoiQXRUSlBwN0NKcm5uSUp0UlRZdWg2Y0hYOFhDMVJXZE8iLCJhcHBfbmFtZSI6IlRlc3RBcHAiLCJjbGllbnRfZW1haWwiOiJ0ZXN0LWRhdGEiLCJjbGllbnRfcGxhdGZvcm0iOiJ0ZXN0LWRhdGEiLCJyZXNwb25zZV90aW1lc3RhbXAiOjE1MDA2NzAzMTV9
            [signature] => pMAoZe0D+9AiAaZ0Kn+JqeiM1RZ9f+6nl2QaYsDpZh0=
        )

Decoded data parameter:

<?php
[
            'req_hash'=>'1234567890asqqwertyuiopASDFGHJKL',
            'app_public_key'=>'app_public_key',
            'app_name'=>'app_name',
            'client_email'=>'client@example.com',
            'client_platform'=>'ios',
            'response_timestamp'=>1500670315
        ]

Event, when client used QR-code from your site.

Type Param Description
string event Event identificator
integer timestamp Date and time of client action. Format UNIX_TIMESTAMP in UTC.
string data Encoded in BASE64 json data
string signature HMAC hash of data parameter

Decoded data parameter:

Type Param Description
string req_hash Unique request hash
string app_public_key Application public key
string app_name Application name
string client_email Client email address
string client_platform Client device platform
integer timestamp Date and time of client action. Format UNIX_TIMESTAMP in UTC.

Push request

[hook] => Array
        (
            [event] => client_push_answer
            [timestamp] => 1500670315
            [data] => eyJyZXFfaGFzaCI6InRlc3QtZGF0YSIsImFwcF9wdWJsaWNfa2V5IjoiQXRUSlBwN0NKcm5uSUp0UlRZdWg2Y0hYOFhDMVJXZE8iLCJhcHBfbmFtZSI6IlRlc3RBcHAiLCJjbGllbnRfZW1haWwiOiJ0ZXN0LWRhdGEiLCJjbGllbnRfcGxhdGZvcm0iOiJ0ZXN0LWRhdGEiLCJyZXNwb25zZV90aW1lc3RhbXAiOjE1MDA2NzAzMTV9
            [signature] => pMAoZe0D+9AiAaZ0Kn+JqeiM1RZ9f+6nl2QaYsDpZh0=
        )

Decoded data parameter:

<?php
[
            'req_hash'=>'1234567890asqqwertyuiopASDFGHJKL',
            'app_public_key'=>'app_public_key',
            'app_name'=>'app_name',
            'answer'=>'true',
            'client_email'=>'client@example.com',
            'client_platform'=>'ios',
            'response_timestamp'=>1500670315
        ]

Event, when client answer “yes” or “no” on Push in mobile application.

Type Param Description
string event Event identificator
integer timestamp Date and time of client action. Format UNIX_TIMESTAMP in UTC.
string data Encoded in BASE64 json data
string signature HMAC hash of data parameter

Decoded data parameter:

Type Param Description
string req_hash Unique request hash
string app_public_key Application public key
string app_name Application name
string answer Request answer
string client_email Client email address
string client_platform Client device platform
integer timestamp Date and time of client action. Format UNIX_TIMESTAMP in UTC.

Timeout

This hook will be fired when Push request expired, (after 30 second user has no action in mobile app).

[hook] => Array
        (
            [event] => client_response_timeout
            [timestamp] => 1500670315
            [data] => eyJyZXFfaGFzaCI6InRlc3QtZGF0YSIsImFwcF9wdWJsaWNfa2V5IjoiQXRUSlBwN0NKcm5uSUp0UlRZdWg2Y0hYOFhDMVJXZE8iLCJhcHBfbmFtZSI6IlRlc3RBcHAiLCJjbGllbnRfZW1haWwiOiJ0ZXN0LWRhdGEiLCJjbGllbnRfcGxhdGZvcm0iOiJ0ZXN0LWRhdGEiLCJyZXNwb25zZV90aW1lc3RhbXAiOjE1MDA2NzAzMTV9
            [signature] => pMAoZe0D+9AiAaZ0Kn+JqeiM1RZ9f+6nl2QaYsDpZh0=
        )

Decoded data parameter:

<?php
[
            'req_hash'=>'1234567890asqqwertyuiopASDFGHJKL',
            'app_public_key'=>'app_public_key',
            'app_name'=>'app_name',
            'client_email'=>'client@example.com',
            'client_platform'=>'ios',
            'response_timestamp'=>1500670315
        ]

Event, when client answer “yes” or “no” on Push in mobile application.

Type Param Description
string event Event identificator
integer timestamp Date and time of client action. Format UNIX_TIMESTAMP in UTC.
string data Encoded in BASE64 json data
string signature HMAC hash of data parameter

Decoded data parameter:

Type Param Description
string req_hash Unique request hash
string app_public_key Application public key
string app_name Application name
string client_email Client email address
string client_platform Client device platform
integer timestamp Date and time of client action. Format UNIX_TIMESTAMP in UTC.
PHP