Bearer token authentication

Data from Participant to Flexible Power

This service supports only bearer token authentication

Only users that have been provided with a valid Api key can use this API. You must include the api key in the Authorization header:

curl -H "Authorization: Bearer API_KEY" http://the-url

Verifying signatures

Data from Flexible Power to Participant

The X-Signature header contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid signature scheme is v1.

X-Signature: t=1519042603,v1=V7bQjPcR1PvUntdftLji9eyMUk4j/3LaXeqTD+QMtoU=

We generate signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you should ignore all schemes that are not v1.

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.
The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature(s). You can discard all other elements.

Step 2: Prepare the signed_payload string

You achieve this by concatenating:

  • The timestamp
  • The character .
  • The actual JSON payload (i.e., the request’s body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use your participant access token as the key, and use the signed_payload string as the message. Base64 encode the bytes to obtain a textual representation of the signature.

Step 4: Compare signatures

Compare the signature(s) in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within 5 minutes.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.