Skip to content

Retailer API

Authorization

Emulate API supports authorization with a JSON Web Token signed with a public/private key pair. The body of the token contains the retailer's ID provided by Emulate.

When you create a token, you can choose its expiration period according to your preferences. You may choose a long expiration period or set it to a short time to implement a policy of regular token changes.

Emulate API uses RS256 as the signing algorithm. To sign the JWT, you can either use a public/private key pair generated by any third-party tool of your choice or generate a key pair in the Emulate portal.

After generating your JSON Web Token, you can use it in the Authorization header of HTTP requests to the Emulate Retailer API.

Key generation

To generate a public/private key pair in the Emulate portal, follow the steps below:

  1. Log in to the Emulate portal in either the stage environment or the production environment.
  2. Navigate to API Settings and open the Key Management tab.
  3. Under Retailer API, go to the Generate Key Pair section.
  4. Enter a key name for your reference and click Generate. The app generates a public/private key pair and displays the private key in a popup window.
  5. Copy and save the private key. The private key is only displayed once and is not saved by the Emulate app. You must save it locally for signing JWT tokens with it.
  6. Verify that your public key is added to the Existing keys list. It should show the key name and the generation date.

Private key security best practices

Keep your private key in a secrets store or a similar mechanism and have it injected into the application as an environment variable or obtained by the application. Never embed the key directly into code or check it into source control.

Emulate additionally recommends the following best practices of storing private keys:

  • Use different keys for a testing/staging and production environments.
  • Use different keys for different applications.
  • Rotate keys periodically, that is, generate a new key and remove the old key from the Emulate portal after the tokens signed with that key have expired.

Signing of the JSON Web Token

Use your private key to sign the JSON Web Token and make sure you select the RS256 algorithm. The example below shows the JWT signature in Node.js, where the private key is passed as the key variable and the Emulate retailer ID as the retailerId variable.

Example of the JWT payload:

{
aud: 'https://api.emulate.network/',
retailer: retailerId
}

npm install jsonwebtoken
const jwt = require('jsonwebtoken');
const privateKey = "<some key>";
// Please replace with the real one
const retailerId = 1;
const payload = {
aud: 'https://api.emulate.network/',
retailer: retailerId,
}
let token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });

The aud parameter must always be set to https://api.emulate.network/, regardless of the Emulate environment you are using.

What to read next

→

The API Reference contains a complete description of the API. You can download the OpenAPI specification to use in your applications.