API keys and webhooks

Keys

An API key belongs to exactly one organization. There is no parameter that selects a different one, so the tenant boundary is identical for the API and the interface.

Create keys with the narrowest scopes that do the job. The key is shown once at creation and only its hash is stored — VitalFax cannot show it to you again, which is also why it cannot be stolen from us.

Revoking a key takes effect on the next request.

Idempotency

Send an Idempotency-Key header on any write. Repeating a request with the same key returns the original result instead of performing the action again, which means a network timeout on your side cannot produce a second fax.

Keys are remembered for 24 hours. Use a fresh UUID per logical operation, not per retry.

Webhooks

Every webhook is signed. Verify the signature over the raw request body before parsing it — parsing first and verifying afterwards defeats the purpose.

Each delivery carries a timestamp and an id. Reject a timestamp outside your tolerance, and treat a repeated id as a duplicate: that combination is what makes replay attacks ineffective.

Respond 2xx within ten seconds. Non-2xx responses are retried with increasing gaps; do your real work after acknowledging.