Getting Started

Getting an API Key and Secret

Please contact us to have an API key and secret issued for your needs.

Once you have your API key and secret, you will need to use both of them to authenticate with the API. We utilize HMAC signature verification to validate the requests.

Making signed requests

The API Key must be sent using the x-api-key header.

The API Secret is used to generate an HMAC signature, with a timestamp included, and the signature must be sent using the x-signature header.

All requests must also include the x-req-timestamp header.

WARNING

Notice we send the key, the timestamp, and the signature. The secret should never be transmitted over the wire.

Signature Generation Process

The signature generation follows these steps:

1. Hash the secret using SHA256:

   hashed_secret = SHA256(your_secret)

2. Construct the payload to sign in the format:

   payload = METHOD:URL_PATH:TIMESTAMP:BODY

   • METHOD: HTTP method (GET, POST, etc.)
   • URL_PATH: Request path including query parameters (e.g., /rest/v1/sites?from=2024-01-01)
   • TIMESTAMP: Unix timestamp in seconds
   • BODY: Request body as JSON string (empty string if no body)

3. Generate the HMAC-SHA256 signature using the hashed secret:

   signature = HMAC-SHA256(payload, hashed_secret)

4. Send in request headers as hex-encoded string

Example Implementation

const crypto = require('crypto');

function makeSignedRequest(method, path, body, apiKey, apiSecret) {
    const timestamp = Math.floor(Date.now() / 1000);

    // 1. Hash the secret using SHA256
    const hashedSecret = crypto
        .createHash('sha256')
        .update(apiSecret)
        .digest('hex');

    // 2. Construct the payload to sign
    let payloadToSign = `${method}:${path}:${timestamp}:`;
    if (body) {
        payloadToSign += JSON.stringify(body);
    }

    // 3. Create the signature using the hashed secret
    const signature = crypto
        .createHmac('sha256', hashedSecret)
        .update(payloadToSign)
        .digest('hex');

    // 4. Send headers
    return fetch(`https://chargepilot-api.tmhusa.energy/rest/v1${path}`, {
        method: method,
        ...(body ? { body: JSON.stringify(body) } : {}),
        headers: {
            'Content-Type': 'application/json',
            'x-api-key': apiKey,
            'x-req-timestamp': timestamp.toString(),
            'x-signature': signature,
        }
    });
}

Liveness checks

An unauthenticated endpoint is available at the path /rest/v1/ping for automated liveness checks. When the Rest API is healthy and available, this endpoint will return a HTTP 200 response.

Example request:

curl -X GET https://chargepilot-api.tmhusa.energy/rest/v1/ping

Sample response:

{ "result": "ChargePilot Rest API is available" }