Flows and protocol

We use two pairs of keys – one for server applications (back-end) and one for publicly available clients (mobile applications and web apps).

Voucherify uses OAuth 2.0 as an authentication protocol for both. It is published under the RFC 6749.

Application authentication

In order to get access to the Voucherify API, a client application needs to pass Application ID and Application Secret Key. You can get (and reset) these tokens in the Project settings.

There are two pairs of authentication keys you're going to use in your requests. The first, Application keys, are meant to authorize your requests to Voucherify API.

The second, Client-side keys, should be use to authorize requests invoked by the public (web and mobile) clients to access a subset of the API.

A generated pair of Application ID and Application Secret Key must be attached to every HTTP request as properly named custom headers: X-App-Id, X-App-Token.

X-App-Id: 2f7075c7-201d-471f-a249-3XXXX8092e70
X-App-Token: 7ccb680d-107e-XXXX-8466-1f15048e34f4

Most likely you won't need to send the token manually. We provide a growing number of SDKs that know how to handle it, so no extra code is needed.


Security threat

It is essential that you secure your tokens and not expose it to others. Treat it as your application's password for Voucherify.

Client-side authentication

The second authentication mechanism uses publishable keys. It's meant to be used by the public (web and mobile) clients to access a subset of the API. See voucherify.js as an example.


Domain whitelist

Remember to whitelist your domain/mobile app origin in the Project settings > Client-side Settings to allow client-side connections. See the picture below

Client-side request headers

For client-side HTTP requests, you need to provide the following headers:

  -H "X-Client-Token: YOUR-CLIENT-SIDE-TOKEN" \
  -H "Content-Type: application/json" \
  -H "origin:" \

Here's an example client-side request (redemption) authorized using client-side API keys.

curl -X POST \
  -H "X-Client-Application-Id: 011240bf-d5fc-4ef1-9e82-11eb68XXXXX" \
  -H "X-Client-Token: 9e2230c5-71fb-460a-91c6-fbee647XXXX" \
  -H "Content-Type: application/json" \
  -H "origin:" \
  -d '{
    "customer" : {
        "source_id" : "track_+EUcXP8WDKXGf3mYmWxbJvEosmKXi3Aw",
        "name": "Alice Morgan"
    "order" : {
        "amount" : 1000,
        "items" : [
            { "product_id": "prod_Bi7sRr3kwvxH2I", "sku_id": null, "quantity": 1 }
    "metadata" : {
        "referrer": ""
  }' \

Did this page help you?