API keys and signing

An API key is a key id and an Ed25519 key pair. MFX Hub keeps the public half; the private half is shown once, at issue, and never stored. Every request is signed with it; the SDK writes the headers, you never do.

Issuing a key

In the customer portal, choose Keys, then Issue a key. Copy the private key into your secret store; the page does not show it again.

Rotating

Issue a new key, move your application to it, then revoke the old one. Both work during the overlap.

What is signed

Four headers go on every request, and on the WebSocket upgrade:

X-MFX-Key: k_01J9...
X-MFX-Timestamp: 1761034323000
X-MFX-Nonce: 9fK2xQ7mLp0aZr4T
X-MFX-Signature: ...

• X-MFX-Timestamp is the time in milliseconds since the Unix epoch. A request more than 30 seconds from MFX Hub’s clock is refused.
• X-MFX-Nonce is unique per key for 5 minutes: 16 to 64 characters of A-Z, a-z, 0-9, _ and -. A nonce seen again is refused, so a captured request cannot be sent twice.
• X-MFX-Signature is the base64 Ed25519 signature, made with your private key, of these five lines joined by a newline:

<timestamp>
<nonce>
<METHOD>
<path with query, e.g. /v1/terminals?limit=50>
<sha256 of the body, lower-case hex; of the empty string when there is no body>

The nonce is inside the signed string, so it cannot be swapped for a fresh one. A refused signature is 401 auth_error, and details.reason says which part: missing_headers, timestamp_not_epoch_ms, nonce_format, timestamp_skew, nonce_replayed, unknown_key, expired_key or bad_signature.