Skip to content

Emulate Web View Documentation

Authorization

Emulate API supports authorization with a JSON Web Token signed with a public/private key pair. Per each customer, a retailer should generate a separate token containing that customer's details. The token is created with an expiration date of the retailer's choosing, and will be valid up until that time. A token with a longer lifetime will allow the customer to bookmark the Emulate Web View and return to it without having to log in to their retailer's site or portal again.

The token is used to form a link to the Emulate Web View.

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.

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. The stage environment and the production environment are completely isolated from each other. Keys, tokens, customer details, and other data are never shared between them. Make sure you choose the correct environment when creating your keys.
  2. Navigate to API Settings and open the Key Management tab.
  3. Under Single Customer API, go to the Generate Key Pair section. The Emulate Web View uses the Single Customer API. Make sure you choose the correct API before generating your key pair.
  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:

  • Your Emulate retailer ID provided by Emulate.
  • Customer identifier used to locate customers on the Emulate portal.
  • Customer facility details: Mandatory parameters

Creation of JSON Web Token payload

The body of the JWT contains information of the customer including a unique customer identifier and a list of customer's facilities. To create the payload, you need the following details:

  • Your Emulate retailer ID provided by Emulate.
  • Customer identifier used to locate customers on the Emulate portal.
  • Customer facility details:
    • Mandatory parameters:
      • Facility ID.
      • Facility address.
      • Price area applicable to the facility (for example, SE1). Price areas are used in spot price optimization.
    • Optional parameters:
      • Facility location (latitude and longitude). If omitted, the Emulate app determines the location by geocoding the facility address.
      • Facility power grid ID that may be used for local intraday trading.

You can use sample data for testing purposes, however, make sure that you do your tests in the testing environment only.

Example of JWT payload:

{
// Audience (a fixed string indicating the JWT is for Emulate; you
// should send it exactly as shown here.)
"aud": "https://api.emulate.network/",
// Your Emulate retailer ID
"retailer": 1,
// Expiration time for this JWT, in seconds since the UNIX epoch.
// Optional, but recommended, otherwise, the token is valid
// indefinitely.
"exp": 1649773792,
"customer": "23421",
"facilities": [
{
// ID of the customer's facility.
"id": "ABC1323",
// Address of the facility.
"address": "Sankt Petri kyrkogata 7, 222 21 Lund, Sweden",
// Price area of the facility.
"price_area": "SE3",
// Optionally, coordinates of the facility.
"location": {
"lat": 55.7063455,
"lng": 13.1913016
},
// Optionally, ID of the power grid to which the facility
// belongs.
"grid_id": "LND"
}
]
}

Signing of the JSON Web Token

Use your private key to sign the JSON Web Token. The example below shows the JWT signature in Node.js, where the private key is passed as the key variable and the JWT payload - as the payload variable:

npm install jsonwebtoken
const jwt = require('jsonwebtoken');
const privateKey = "<some key>"
const addDays = (days) =>
new Date().setDate(new Date().getDate() + days)
const payload = {
// Audience (a fixed string indicating the JWT is for Emulate; you
// should send it exactly as shown here.)
"aud": "https://api.emulate.network/",
// Your Emulate retailer ID
"retailer": 1,
// Expiration time for this JWT, in seconds since the UNIX epoch.
// Optional, but recommended, otherwise, the token is valid
// indefinitely.
"exp": addDays(7),
// ID of your customer.
"customer": "23421",
// An array of, at least, one facility (location where the customer has
// a power meter).
"facilities": [
{
// ID of the customer's facility.
"id": "ABC1323",
// Address of the facility.
"address": "Sankt Petri kyrkogata 7, 222 21 Lund, Sweden",
// Price area of the facility.
"price_area": "SE3",
// Optionally, coordinates of the facility.
"location": {
"lat": 55.7063455,
"lng": 13.1913016
},
// Optionally, ID of the power grid to which the facility
// belongs.
"grid_id": "LND"
}
]
}
let token = jwt.sign(payload, privateKey, { algorithm: 'RS256'});

What to read next

→

The app testing helps you verify how Emulate’s Web View behaves when triggering app-to-app deep links from within a native mobile app’s embedded web browser