--- title: "HMAC Concepts" slug: "hmac-concepts" tags: ["administration", "security", "authentication", "reference-guides"] updated: 2026-09-11T19:13:47Z published: 2026-09-15T20:09:25Z canonical: "docs.unqork.io/hmac-concepts" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # HMAC Concepts 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](/unqorkai/docs/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 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 upon in advance and never sent along with requests. When Unqork sends a request, it: 1. Takes the content of the request. 2. Combines it with the shared secret key. 3. Runs the combination through a hash function (SHA-256 by default) to produce a fixed-length signature. 4. 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 . 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](/unqorkai/docs/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 | | **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](/unqorkai/docs/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](/unqorkai/docs/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. | APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases. Transport Layer Security (TLS) is a protocol that provides communication security across a network. Base64 is an encoding and decoding technique used to convert binary data to an ASCII (American Standard for Information Interchange) text format. Includes the Short Answer component, Long Answer component, Select Boxes, Radio component, Dropdown, Number component and Single Checkbox. OAuth, or Open Authorization, is an authorization protocol that lets users grant third-party access to their information without sharing their passwords. OAuth is an industry standard that's used by many companies, including Google, Amazon, and Microsoft. A JSON Web Token (JWT) is used to identify an authenticated user. They are issued by an authentication server to secure use on aclient server. An API endpoint is the location where an API receives requests for a specific resource on its server. It's the point of contact between an API client and an API server, and is usually a uniform resource locator (URL) that provides the location of the resource. APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases. HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.