Skip to main content
Responses to secret-key calls that return money records carry a signature. A server that holds the signing secret recomputes it and confirms that the body is the one Galactic Core produced and was not altered on the way, for example by a proxy that terminates TLS in front of your server. The signature is the response-side counterpart of the request signature and uses the same recipe and the same secret.

Signed operations

A return carries its refund amount, method and status, so listReturns and getReturn are the signed reads for refunds. A response is signed when the call is made with a secret key and the store has a signing secret. A call made with a publishable key is never signed, because a publishable key holds no secret to verify with. A call made with a marketplace key to the returns operations is not signed. Every other operation returns no signature headers.

Signature headers

{timestamp} is the value of X-Signature-Timestamp and {body} is the exact bytes of the response after transport decompression. The body is neither parsed nor re-serialised: a different key order or different whitespace is a different string and produces a different signature.

Signing secret

The secret that signs a response is the one the caller uses to sign requests:
  • A key issued to an application connected through Login with GC signs with that connection’s own signing_secret.
  • Any other key signs with the store’s signing secret, shown under Integrations → API keys.
During a rotation, a verifier that holds both the old and the new secret accepts a response that verifies under either.

Verifying with the SDK

verifyResponseSignature recomputes the signature with Web Crypto and compares it in constant time. It runs on Node.js 18 and later and on other server runtimes that provide Web Crypto.
The function returns true when the signature matches under any supplied secret and the timestamp is within tolerance. It returns false for a missing or malformed header, a stale timestamp, a changed body and a wrong secret. A response that carries no signature headers returns false. The generated service methods return parsed objects, so a response is verified on a direct fetch call as above.

Verifying without the SDK

The recipe has four steps:
  1. Read X-Signature-Timestamp and X-Signature from the response.
  2. Take the decoded response body as received.
  3. Compute HMAC-SHA256(signing_secret, "{timestamp}.{body}") and encode the digest as base64.
  4. Compare it with X-Signature in constant time, and reject a response whose timestamp is more than five minutes from the current time.

What a signature establishes

A valid signature establishes that the body was produced by Galactic Core for a holder of the signing secret and that it has not changed since. The timestamp lets a verifier reject a response that is older than its tolerance. A signature is not authentication, is not a substitute for TLS, and says nothing about the request that was sent. A signing secret belongs on a server. A browser holds no secret and receives no signed responses.