Skip to content

Single Customer API

Authorization

Emulate API supports authorization with a JSON Web Token signed with a public/private key pair. Per each customer, a separate token containing that customer's details is to be generated.

When the token is used in the Authorization header of HTTP requests to the Emulate Single Customer API, it is validated as produced by the retailer for a specific customer. Each token provides access only to the data of a single customer.

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.
  2. Navigate to API Settings and open the Key Management tab.
  3. Under Single Customer 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.

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 API Reference contains a complete description of the API. You can download the OpenAPI specification to use in your applications.