Signing requests

Sign pushes, embed address requests, table sync and disconnect with HMAC-SHA256 over the method, path, timestamp and exact body bytes.

Updated 7 November 2026 · View as Markdown

Four endpoints take signed requests: POST /api/live/ingest, POST /api/live/embed-tokens, POST /api/connections/self/tables and DELETE /api/connections/self. Each request carries three headers, made from the connectionId and connectionSecret your server got when it connected.

Headers

The signed text

Join these five parts with a line feed (\n), with nothing after the body:

1. v1
2. The method in upper case: POST or DELETE
3. The path only, with no scheme, host, port or query, such as /api/live/ingest
4. The X-FPC-Timestamp value
5. The raw body bytes, exactly as sent. An empty body is zero bytes.

The HMAC key is the connectionSecret text as UTF-8 bytes. Do not base64-decode it first.

Serialise the body once and send exactly the bytes you signed. Because the method and the path are signed, a request signed for one endpoint is refused by every other.

Example in TypeScript

import { createHmac } from "node:crypto";

const ORIGIN = "https://floorplancraft.com";

/** A signed request. body is the exact JSON text to send, or null to send none. */
export async function signedRequest(method: "POST" | "DELETE", path: string, body: string | null,
  connectionId: string, connectionSecret: string): Promise<Response> {
  const timestamp = String(Math.floor(Date.now() / 1000));
  const signed = ["v1", method, path, timestamp, body ?? ""].join("\n");
  const signature = createHmac("sha256", Buffer.from(connectionSecret, "utf8")).update(signed, "utf8").digest("hex");
  const headers: Record<string, string> = {
    "X-FPC-Connection": connectionId,
    "X-FPC-Timestamp": timestamp,
    "X-FPC-Signature": "v1=" + signature,
  };
  if (body !== null) headers["Content-Type"] = "application/json";
  return fetch(ORIGIN + path, { method, headers, body: body ?? undefined });
}

// connectionId and connectionSecret come from your server's own store.
const heartbeat = JSON.stringify({ at: new Date().toISOString(), heartbeat: true, sequence: 1288 });
await signedRequest("POST", "/api/live/ingest", heartbeat, connectionId, connectionSecret);
await signedRequest("DELETE", "/api/connections/self", null, connectionId, connectionSecret);

Test vectors

With the synthetic secret 0bsCgj_qUCHf4yNLsu7uPYpWYy07SC8jpQzqXHK_9jI, X-FPC-Timestamp: 1760875200 and bodies with no trailing line feed:

Signing errors

Each of these failures, and an oversized body, counts against your server's address: 60 at once, then 60 a minute. Past that, every signed request from the address gets 429 before any other check.