{"id":84230,"date":"2022-08-03T22:50:08","date_gmt":"2022-08-03T14:50:08","guid":{"rendered":"https:\/\/www.ahhhhfs.com\/84230\/"},"modified":"2026-10-17T00:28:49","modified_gmt":"2026-10-16T16:28:49","slug":"what-is-hmac-how-to-sign-api-requests-with-hmac-sha256","status":"publish","type":"post","link":"https:\/\/www.ahhhhfs.com\/en\/84230\/","title":{"rendered":"What Is HMAC? How to Sign API Requests with HMAC-SHA256"},"content":{"rendered":"

HMAC authentication<\/strong> is widely used for API request signing, webhook verification, and server-to-server communication. Its job is not to encrypt a request. It lets a server verify that a message was created by someone who holds the shared secret, and that the signed parts of the request were not changed in transit.<\/p>\n

A common design is to build a canonical request from the HTTP method, path, query string, selected headers, a payload hash, a timestamp, and a nonce. The client signs that canonical representation with HMAC-SHA256. The server rebuilds the same input, calculates its own HMAC, and compares the result with the signature sent by the client.<\/p>\n

The HMAC calculation itself is straightforward. Most implementation mistakes happen around canonicalization, replay protection, secret handling, and deciding exactly which request fields are covered by the signature.<\/p>\n

What is HMAC authentication?<\/h2>\n

HMAC<\/strong> stands for Hash-based Message Authentication Code. RFC 2104 defines it as a message authentication mechanism built from a cryptographic hash function and a shared secret key.<\/p>\n

At a high level:<\/p>\n

HMAC = Hash Function + Secret Key + Message<\/code><\/pre>\n
A plain SHA-256 hash only needs the message:<\/p>\n
SHA256(message)<\/code><\/pre>\n
HMAC also requires a secret key:<\/p>\n
HMAC-SHA256(secret_key, message)<\/code><\/pre>\n
Anyone who has the message can calculate a normal SHA-256 hash. Calculating the correct HMAC requires the shared secret as well.<\/p>\n
That gives HMAC two useful properties for API protocols: it can detect changes to signed data, and it can verify that the message was produced by a party that knows the shared secret.<\/p>\n
There is an important limitation. Both sides hold the same secret. HMAC therefore does not provide the same non-repudiation properties as an asymmetric digital signature such as RSA or ECDSA. Either holder of the shared key could have produced the HMAC.<\/p>\n
How HMAC-SHA256 API request signing works<\/h2>\n
Signing only the request body is usually not enough. The server needs to know which request was authorized, not just whether a block of JSON stayed unchanged.<\/p>\n
Suppose a client sends:<\/p>\n
POST \/api\/orders?currency=USD<\/code><\/pre>\n
with this JSON body:<\/p>\n
{\r\n  \"product_id\": \"A1024\",\r\n  \"quantity\": 2\r\n}<\/code><\/pre>\n
The client can start by hashing the request body:<\/p>\n
body_hash = SHA256(request_body)<\/code><\/pre>\n
It then builds a canonical request. A simplified format might look like this:<\/p>\n
POST\r\n\/api\/orders\r\ncurrency=USD\r\ncontent-type:application\/json\r\nx-client-id:client_123\r\nx-timestamp:1712345678\r\nx-nonce:550e8400-e29b-41d4-a716-446655440000\r\ncontent-type;x-client-id;x-timestamp;x-nonce\r\n<body_sha256><\/code><\/pre>\n
This example covers:<\/p>\n