diagram.mmd — sequence
API Request Signing sequence diagram

API request signing is a security technique where the client includes a cryptographic signature over the request's components — method, URL, headers, and body — so the server can verify the request's authenticity and integrity and reject replayed or tampered requests.

The most well-known implementation is AWS Signature Version 4 (SigV4), used by all AWS services. Similar schemes are used by Azure, Google Cloud, and many payment processors. The core principle is always the same: the client constructs a canonical representation of the request, signs it with a secret key (typically via HMAC-SHA256), and includes the signature in the Authorization header.

The signing process involves several steps. First, the client canonicalizes the request: normalizing the URL path, sorting query parameters, lowercasing and sorting header names, and hashing the request body. This produces a deterministic string representation regardless of how the HTTP client orders headers. Second, the client constructs a string to sign that includes the algorithm name, timestamp, and the hash of the canonical request. Third, the client computes an HMAC over this string using its secret key (possibly after a key derivation step as in SigV4).

The server repeats the same canonicalization and signing steps using the client's known secret key, then compares its computed signature to the one in the request. Because the signature covers the timestamp, the server enforces a replay window — typically 5–15 minutes — rejecting requests whose timestamp is too old. This prevents replay attacks where an attacker captures a valid signed request and re-submits it.

Request signing provides stronger security than bearer tokens alone because a stolen signed request only works for a short window, and the signature covers the exact request contents — an attacker cannot modify the payload without invalidating the signature. See HMAC Signing Process for the underlying signature mechanism and Secure API Gateway for the broader API security architecture.

Free online editor
Edit this diagram in Graphlet
Fork, modify, and export to SVG or PNG. No sign-up required.
Open in Graphlet →

Frequently asked questions

API request signing is a security technique where the client computes a cryptographic signature over the canonical form of the request — method, URL, headers, and body hash — and includes that signature in the `Authorization` header. The server recomputes the signature and rejects any request where the values do not match.
The signature covers a timestamp included in the canonical request. The server enforces a replay window (typically 5–15 minutes) and rejects any request whose timestamp falls outside that window. An attacker who captures a valid signed request cannot re-use it after the window closes.
Use request signing when you need message-level integrity guarantees — ensuring the payload cannot be tampered with in transit — and when stronger replay protection than a short-lived bearer token provides is required. AWS SigV4, webhook verification, and payment processor APIs are the most common use cases.
mermaid
sequenceDiagram participant Client participant Gateway as API Gateway / Server participant KeyStore as Key Store Client->>Client: Build canonical request\n(method + URL + headers + body hash) Client->>Client: Construct string to sign\n(algorithm + timestamp + canonical hash) Client->>Client: Compute HMAC-SHA256\nover string to sign using secret key Client->>Gateway: HTTP Request with Authorization header\nHMAC-SHA256 Credential and Signature fields note">Note over Gateway: Validate timestamp\n(reject if > 5 min old) Gateway->>KeyStore: Look up secret key\nby key-id from Authorization header KeyStore-->>Gateway: Return secret key Gateway->>Gateway: Rebuild canonical request\nfrom received headers and body Gateway->>Gateway: Compute expected HMAC-SHA256\nusing retrieved secret key Gateway->>Gateway: Constant-time compare\nreceived vs computed signature alt Signatures match Gateway-->>Client: 200 OK + response body else Mismatch or expired Gateway-->>Client: 401 Unauthorized end
Copied to clipboard