Signing requests

A bearer key is enough for most tools. Signing is for the ones where a leaked key would matter more than a leaked password: it binds each request to a secret that never leaves your machine, so a key copied out of a log, a proxy or a screenshot cannot be used without it.

Turning it on

From Selling, then Integrations, switch a key to signed requests. You get a signing secret, fpsig_…, once. From that moment every request with that key must be signed; an unsigned one is refused with signature_required, which is a 401, so a tool that was not ready fails loudly and immediately rather than sometimes.

The signature

1. Take the current time as unix seconds, t.
2. Build the string t.METHOD.request-target.sha256hex(body): the method in upper case, the request target as the path and query exactly as you send them (/v1/listings?limit=50), and the hex SHA-256 of the raw body bytes, or of the empty string when there is no body.
3. HMAC-SHA256 that string with the signing secret; hex-encode the result.
4. Send Freeport-Timestamp: t and Freeport-Signature: v1=<hex> beside the bearer header.

A signature is accepted once, inside a five-minute window around t; a replay inside the window is refused with signature_replayed, and a drift past it with signature_expired. Keep your clock right.

What to sign with

The body bytes you actually send. If your HTTP library re-serialises JSON, sign the string it will put on the wire, not the object you built; the cheapest way is to serialise first and pass the string to both the hash and the request. The samples do it that way.