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.