Hash-based Message Authentication Code (HMAC) is a cryptographic method for verifying both the integrity and authenticity of a message. In Unqork, HMAC is available as a service authentication type in Services Administration and is used to sign outbound API requests to external systems that require request authentication.
HMAC works by combining a message with a shared secret key and running it through a hash function. The result is a short, fixed-length signature that proves the message came from a trusted sender and was not changed in transit. Unqork uses SHA-256 as the default hash function.
How HMAC Works
HMAC uses a shared secret key that both the sender and the receiver hold. That secret is agreed on in advance and never sent along with requests.
When Unqork sends a request, it:
Takes the content of the request.
Combines it with the shared secret key.
Runs the combination through a hash function (SHA-256 by default) to produce a fixed-length signature.
Attaches that signature to the outbound request.
The receiver runs the same calculation using its own copy of the shared secret. If the two signatures match, the receiver knows two things:
Integrity: The message was not changed in transit.
Authenticity: The sender holds the correct shared secret and is who they claim to be.
Unlike certificate-based methods like Mutual TLS, HMAC does not use a public and private key pair. It relies on a single shared secret that only the two parties know. The secret itself is never transmitted.
HMAC Settings in Unqork
HMAC services are configured in Services Administration. When creating a service with the HMAC authentication type, provide the following:
Field | Description |
|---|---|
HMAC Private Key (Armored) | The HMAC key shared with the external service. Stored in armored (Base64-encoded) format. |
Unqork supports two hash algorithms and two output encoding options when computing HMAC signatures:
Setting | Options | Default |
|---|---|---|
Hash Algorithm | SHA-256, SHA-512 | SHA-256 |
Output Encoding | Base64, Hex | Base64 |
All HMAC configuration is stored server-side. The private key is never exposed to the browser.
How Unqork Uses HMAC
When a service uses HMAC authentication, Unqork computes the HMAC signature at runtime using the stored private key. The signature is attached to the outbound request, typically in a request header. The external system then verifies the signature using its own copy of the shared secret.
The private key is stored encrypted at rest. Unqork never includes the key itself in outbound requests.
HMAC services in Unqork are server-side only. They cannot be called directly from the browser and must run through server-side execution.
View Service Types for the complete field reference and configuration details for the HMAC service type.
Supported Authentication Types
HMAC is configured at the service level and applies to the HMAC authentication type. Some other Unqork authentication types also use HMAC algorithms internally for token signing.
Authentication types that support HMAC:
Authentication Type | HMAC Usage |
|---|---|
HMAC | Native HMAC authentication. Signs outbound requests using a shared secret key. |
OAuth 2 JWT Bearer Grant | Supports HS256 (HMAC with SHA-256) as a JWT signing algorithm for token generation. |
Authentication types that do not support HMAC:
Mutual TLS (mTLS) certificates cannot be used with HMAC services. HMAC does not use certificates. If the external system requires verified client identity through certificates, a separate mTLS-configured service is needed.
See Mutual TLS Concepts for more information on certificate-based authentication.
When to Use HMAC
Use HMAC authentication when the external system requires signed requests to prove message integrity and sender identity. Common examples include:
Webhook endpoints that validate incoming requests using a shared secret.
APIs that require HMAC signatures in request headers.
Integrations where the external system cannot support OAuth or certificate-based authentication.
HMAC Terminology
Term | Definition |
|---|---|
Shared Secret | A private key known to both the sender and the receiver. It is set up in advance over a secure channel and never transmitted during requests. |
HMAC Signature | The fixed-length code produced by combining a message with a shared secret and running it through a hash function. |
Hash Function | A one-way mathematical function that converts input data into a fixed-length output. The same input always produces the same output, but the process cannot be reversed to recover the original data. |
SHA-256 | The hash function Unqork uses for HMAC by default. The "256" refers to the 256-bit length of the output signature. |
SHA-512 | An alternative hash function that produces a 512-bit signature. Supported by Unqork as an option for higher output length. |
Base64 Encoding | A way to represent binary data as plain text characters. HMAC keys and signatures are often Base64-encoded for safe use in HTTP headers. |
Hex Encoding | An alternative encoding that represents binary data using hexadecimal characters (0-9, a-f). |
HS256 | The JWT algorithm name for HMAC with SHA-256. Used by OAuth 2 JWT Bearer Grant to sign tokens. |
Armored Format | A text-safe encoding of a cryptographic key, typically Base64, that makes the key safe to store and transmit in configuration fields. |
Changelog
Date | Change |
|---|---|
2026-05-12 | Expanded with HMAC settings, supported authentication types, terminology glossary, and mTLS incompatibility note. [MJS] |
— | Initial publication. |