Skip to content

Client signature

Server-to-server integrations that only need the devices of one SplashMe account can skip the OAuth2 flow. Each request carries a signature computed with the client secret; the gateway authenticates it as the account that registered the client. There is no sign-in page, no token and nothing to refresh.

Use the OAuth2 flow instead when your application acts for other users’ accounts.

Send all four headers on every request. A request with all four is authenticated by signature and any Authorization header is ignored; a request missing any of them falls back to bearer token authentication.

Header Value
X-Client-Id Your client_id
X-Timestamp Current Unix time in seconds
X-Nonce A random string unique to this request, at least 16 random bytes encoded
X-Signature Lower-case hex HMAC-SHA256 of the string to sign, keyed with client_secret

Join five fields with a newline (\n), no trailing newline:

<METHOD>\n<request URI>\n<client_id>\n<timestamp>\n<nonce>
  • METHOD is upper case, for example GET or POST.
  • The request URI is the path plus query string exactly as sent, for example /api-gateway/v1/user/sites or /api-gateway/v2/iot-shadow/device/02_53_4D_00_00_01/events?limit=20. The scheme and host are not included.
  • timestamp and nonce are the exact header values.

The signature is HMAC-SHA256(client_secret, string to sign) as lower-case hex (upper-case is accepted). Both the secret and the string are UTF-8 bytes.

Check your implementation against this before calling the API. With

Field Value
client_id sm_ab3de5fg7h_my-pool-app
client_secret sm_secret_0123456789abcdef0123456789abcdef
Method GET
Request URI /api-gateway/v1/user/sites
X-Timestamp 1760000000
X-Nonce 3f7a9c1e5b2d4e6f8a0b1c2d3e4f5a6b

the string to sign is GET\n/api-gateway/v1/user/sites\nsm_ab3de5fg7h_my-pool-app\n1760000000\n3f7a9c1e5b2d4e6f8a0b1c2d3e4f5a6b and X-Signature must be:

592989b7d2fc5b2934fbecff96fb8285bf744b142f4ba626f1b06ee338d6ef40

Every sample below has a sign function you can call with these values.

Each sample builds the four headers for one request and uses them to list the account’s sites. Only standard-library code; pass the request URI you are about to send, including any query string.

import hashlib, hmac, json, secrets, time, urllib.request
BASE = "https://api.splashmepool.com.au"
def sign(client_secret, method, request_uri, client_id, timestamp, nonce):
message = "\n".join([method.upper(), request_uri, client_id, timestamp, nonce])
return hmac.new(client_secret.encode(), message.encode(), hashlib.sha256).hexdigest()
def signed_headers(client_id, client_secret, method, request_uri):
timestamp = str(int(time.time()))
nonce = secrets.token_hex(16)
return {
"X-Client-Id": client_id,
"X-Timestamp": timestamp,
"X-Nonce": nonce,
"X-Signature": sign(client_secret, method, request_uri, client_id, timestamp, nonce),
}
req = urllib.request.Request(BASE + "/api-gateway/v1/user/sites",
headers=signed_headers(CLIENT_ID, CLIENT_SECRET, "GET", "/api-gateway/v1/user/sites"))
sites = json.load(urllib.request.urlopen(req))["data"]["sites"]
import { createHmac, randomBytes } from "node:crypto";
const BASE = "https://api.splashmepool.com.au";
function sign(clientSecret, method, requestUri, clientId, timestamp, nonce) {
const message = [method.toUpperCase(), requestUri, clientId, timestamp, nonce].join("\n");
return createHmac("sha256", clientSecret).update(message).digest("hex");
}
function signedHeaders(clientId, clientSecret, method, requestUri) {
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString("hex");
return {
"X-Client-Id": clientId,
"X-Timestamp": timestamp,
"X-Nonce": nonce,
"X-Signature": sign(clientSecret, method, requestUri, clientId, timestamp, nonce),
};
}
const requestUri = "/api-gateway/v1/user/sites";
const res = await fetch(BASE + requestUri, { headers: signedHeaders(CLIENT_ID, CLIENT_SECRET, "GET", requestUri) });
const { data } = await res.json();
import (
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"encoding/hex"
"fmt"
"net/http"
"strconv"
"strings"
"time"
)
func sign(clientSecret, method, requestURI, clientID, timestamp, nonce string) string {
message := strings.Join([]string{strings.ToUpper(method), requestURI, clientID, timestamp, nonce}, "\n")
mac := hmac.New(sha256.New, []byte(clientSecret))
mac.Write([]byte(message))
return hex.EncodeToString(mac.Sum(nil))
}
func signRequest(req *http.Request, clientID, clientSecret string) {
timestamp := strconv.FormatInt(time.Now().Unix(), 10)
raw := make([]byte, 16)
rand.Read(raw)
nonce := hex.EncodeToString(raw)
req.Header.Set("X-Client-Id", clientID)
req.Header.Set("X-Timestamp", timestamp)
req.Header.Set("X-Nonce", nonce)
req.Header.Set("X-Signature", sign(clientSecret, req.Method, req.URL.RequestURI(), clientID, timestamp, nonce))
}
req, _ := http.NewRequest(http.MethodGet, "https://api.splashmepool.com.au/api-gateway/v1/user/sites", nil)
signRequest(req, clientID, clientSecret)
resp, err := http.DefaultClient.Do(req)
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.util.HexFormat;
import java.util.Map;
public class Sign {
static String sign(String clientSecret, String method, String requestUri, String clientId, String timestamp, String nonce) throws Exception {
String message = String.join("\n", method.toUpperCase(), requestUri, clientId, timestamp, nonce);
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(clientSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
return HexFormat.of().formatHex(mac.doFinal(message.getBytes(StandardCharsets.UTF_8)));
}
static Map<String, String> signedHeaders(String clientId, String clientSecret, String method, String requestUri) throws Exception {
String timestamp = Long.toString(System.currentTimeMillis() / 1000);
byte[] raw = new byte[16];
new SecureRandom().nextBytes(raw);
String nonce = HexFormat.of().formatHex(raw);
return Map.of(
"X-Client-Id", clientId,
"X-Timestamp", timestamp,
"X-Nonce", nonce,
"X-Signature", sign(clientSecret, method, requestUri, clientId, timestamp, nonce));
}
}
HttpRequest.Builder b = HttpRequest.newBuilder(URI.create("https://api.splashmepool.com.au/api-gateway/v1/user/sites"));
signedHeaders(clientId, clientSecret, "GET", "/api-gateway/v1/user/sites").forEach(b::header);
HttpResponse<String> resp = HttpClient.newHttpClient().send(b.build(), HttpResponse.BodyHandlers.ofString());
using System.Security.Cryptography;
using System.Text;
static string Sign(string clientSecret, string method, string requestUri, string clientId, string timestamp, string nonce)
{
var message = string.Join("\n", method.ToUpperInvariant(), requestUri, clientId, timestamp, nonce);
using var mac = new HMACSHA256(Encoding.UTF8.GetBytes(clientSecret));
return Convert.ToHexString(mac.ComputeHash(Encoding.UTF8.GetBytes(message))).ToLowerInvariant();
}
static Dictionary<string, string> SignedHeaders(string clientId, string clientSecret, string method, string requestUri)
{
var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
var nonce = Convert.ToHexString(RandomNumberGenerator.GetBytes(16)).ToLowerInvariant();
return new Dictionary<string, string>
{
["X-Client-Id"] = clientId,
["X-Timestamp"] = timestamp,
["X-Nonce"] = nonce,
["X-Signature"] = Sign(clientSecret, method, requestUri, clientId, timestamp, nonce),
};
}
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.splashmepool.com.au/api-gateway/v1/user/sites");
foreach (var (name, value) in SignedHeaders(clientId, clientSecret, "GET", "/api-gateway/v1/user/sites"))
request.Headers.Add(name, value);
var response = await new HttpClient().SendAsync(request);
<?php
function sign(string $clientSecret, string $method, string $requestUri, string $clientId, string $timestamp, string $nonce): string {
$message = implode("\n", [strtoupper($method), $requestUri, $clientId, $timestamp, $nonce]);
return hash_hmac('sha256', $message, $clientSecret);
}
function signedHeaders(string $clientId, string $clientSecret, string $method, string $requestUri): array {
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
return [
"X-Client-Id: $clientId",
"X-Timestamp: $timestamp",
"X-Nonce: $nonce",
"X-Signature: " . sign($clientSecret, $method, $requestUri, $clientId, $timestamp, $nonce),
];
}
$ch = curl_init("https://api.splashmepool.com.au/api-gateway/v1/user/sites");
curl_setopt($ch, CURLOPT_HTTPHEADER, signedHeaders($clientId, $clientSecret, 'GET', '/api-gateway/v1/user/sites'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$sites = json_decode(curl_exec($ch), true)['data']['sites'];
Terminal window
CLIENT_ID=sm_ab3de5fg7h_my-pool-app
CLIENT_SECRET=sm_secret_0123456789abcdef0123456789abcdef
METHOD=GET
URI=/api-gateway/v1/user/sites
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIG=$(printf '%s\n%s\n%s\n%s\n%s' "$METHOD" "$URI" "$CLIENT_ID" "$TS" "$NONCE" \
| openssl dgst -sha256 -hmac "$CLIENT_SECRET" | sed 's/^.* //')
curl "https://api.splashmepool.com.au$URI" \
-H "X-Client-Id: $CLIENT_ID" -H "X-Timestamp: $TS" -H "X-Nonce: $NONCE" -H "X-Signature: $SIG"
  1. X-Timestamp is an integer within 5 minutes of the server clock, before or after. Keep your clock synchronised.
  2. client_id exists.
  3. The signature matches, compared in constant time.
  4. The nonce has not been used by this client in the last 5 minutes. A nonce is consumed as soon as the signature verifies, so generate a fresh one for every attempt, including retries.

The request then runs as the client’s owner with the same permissions as a bearer token for that account, including device ownership checks.

Errors use the standard {"status": "FAILED", "message": …} envelope.

Status message Cause
401 Invalid X-Timestamp Not an integer
401 Request timestamp out of allowed window More than 5 minutes from the server clock
401 Unknown client_id No such client
401 Invalid signature Wrong secret or a mismatch in the string to sign
401 Client signature is not available for this client The client has no secret (a public, PKCE-only client)
401 Replay detected Nonce already used within the window
500 Signature verification unavailable The replay store is unavailable; retry later with a fresh nonce