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.
Headers
Section titled “Headers”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 |
String to sign
Section titled “String to sign”Join five fields with a newline (\n), no trailing newline:
<METHOD>\n<request URI>\n<client_id>\n<timestamp>\n<nonce>METHODis upper case, for exampleGETorPOST.- The request URI is the path plus query string exactly as sent, for example
/api-gateway/v1/user/sitesor/api-gateway/v2/iot-shadow/device/02_53_4D_00_00_01/events?limit=20. The scheme and host are not included. timestampandnonceare 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.
Test vector
Section titled “Test vector”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:
592989b7d2fc5b2934fbecff96fb8285bf744b142f4ba626f1b06ee338d6ef40Every sample below has a sign function you can call with these values.
Code samples
Section titled “Code samples”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.
Python
Section titled “Python”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"]Node.js
Section titled “Node.js”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);<?phpfunction 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'];CLIENT_ID=sm_ab3de5fg7h_my-pool-appCLIENT_SECRET=sm_secret_0123456789abcdef0123456789abcdefMETHOD=GETURI=/api-gateway/v1/user/sitesTS=$(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"What the server checks
Section titled “What the server checks”X-Timestampis an integer within 5 minutes of the server clock, before or after. Keep your clock synchronised.client_idexists.- The signature matches, compared in constant time.
- 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
Section titled “Errors”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 |

