Signed order intent

Optionally signing order parameters with an RSA key, for tamper-evidence and non-repudiation.

Signed intent lets you sign the parameters of an order with an RSA private key, so the order carries proof it came from you and was not altered in transit.

It is worth having where an order passes through middleware or an internal gateway before reaching us, or where your own controls require non-repudiation — being able to demonstrate afterwards that a specific order was yours.

API keys work without an RSA key, and orders without a signedIntent are processed normally on standard API authentication. This is an additional layer, not a replacement for it.

Setting it up

Signing is per API key, and set up once.

Generate an RSA key pair — 4096-bit preferred, 2048-bit the minimum.
Register the public key on the API key, either when creating it or by editing it later. See API keys.
Keep the private key where your signing process can reach it and nothing else can.

The public key is PEM, X.509 SubjectPublicKeyInfo — the block between -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----.

Signing an order

The signature covers a base64-encoded payload of the order parameters, and both travel together on the order message:

{
  "payload": "eyJxdW90ZUlkIjoi…",
  "signature": "M4eIw8Db3jKl9xQ2vN7pZ…"
}

Sign the encoded payload, not the raw JSON, and send exactly the bytes you signed. Re-encoding afterwards changes what was signed and the order is rejected.

Rotating keys

Generate a new pair and register the new public key. Both are honoured through a transition window, so signing can move over without an interruption — but confirm the window with your Relationship Manager before relying on it.