Hmac Based Authentication
Available starting Taurus-PROTECT 3.20
In this article
By the end of this document you should have:
- A high level understanding of what HMAC authentication is.
- When to use HMAC authentication and how it differs from the Bearer authentication.
- Familiarity with how Taurus implements HMAC including which fields we sign and how to generate the headers.
- Familiarity with basic code examples (in Python) which show you how to generate signatures and prepare auth headers.
Introduction
HMAC (Hash-based Message Authentication Code) is a method for verifying the integrity and authenticity of a message using a shared secret key. It combines the message and key with a cryptographic hash function (like SHA-256) to produce a signature. This signature ensures the request hasn’t been altered and comes from a trusted source — making it a common choice for securing API requests.
This approach differs from Bearer authentication in that it allows long-lived keys to be used. While Bearer authentication uses the username and password directly to be exchanged for a short-lived token, using the HMAC authentication method allows multiple pre-shared keys which can be secured independently in a secret store, eg. Vault or Azure Key Vault to sign request. Since multiple keys can be stored for each user, 0-downtime key rotation is possible even with eventually consistent key storage systems. Every request must be sent with a signature in the Authorization header.
When to use HMAC Authentication
While the Bearer Authentication describes an approach which works well for development purposes, we recommend implementing production systems against the more robust scheme described in this document. Since keys can be independently secured and rotated, using the HMAC scheme in protect provides tangible security benefits for operating a Taurus Protect installation in business critical environments.
High Level Approach
This document covers, with working code examples and setup instructions, the following high-level flow:
- Generate an API Key in the UI which is used to sign requests.
- Compute an HMAC Signature and base64 encode it.
- Create an API request via with the signature in the
Authorizationheader.
Obtaining an API Key via the UI
Adding a new API key to a user using the Taurus UI adheres to the 4-eyes principle and will require participation of at least two users with user manager roles, typically your administrators.
- Log in as a user with user manager role privileges.
- Navigate to the
Usersmenu on the left navigation bar and open the details for the user you would like to generate keys for. - Expand the
API keyssection and select theHMACtab.

- Click on Generate new API key, which triggers a change request to create an
ApiKeyfor thisUser. This change request must be approved by an additional user with user manager role privileges (typically an administrator). - Log in with a different user manager.
- Navigate to the
Changes -> To Validatemenu and tab. - Approve the change request.

- You can now go back to the
Userdetails page where it will display anApiKey.

- Click on the eye icon next to the API key to reveal the secret.
Important
You will only have one opportunity to record the API key. Ensure you save this in a safe place. If the secret is lost, all the above steps must be repeated to generate a new key and the lost key should be deleted.

- Both the Id and the Secret, are required for signing a request. You don’t need to treat the Id field as sensitive data, but the Secret value must be protected. Make sure you store these in a safe place.
Signing requests using the HMAC secret
This section walks through the steps involved in generating and verifying HMAC signatures — including how to construct the message, handle timestamps and nonces, and securely transmit the signature with each request. Following these conventions ensures both sides can trust the integrity and origin of the data.
At a high level, to generate an HMAC signature you will be:
- Collecting 10 pieces of information (called HMAC parts).
- Concatenate the parts with one whitespace character (
0x20) in the correct order. Skip empty parts (ie. do not use double spaces). - Generate a
HMAC-SHA265signature with the API key and the combined HMAC parts.
The HMAC Signature is made up of 9 parts plus the request body and the table below describes each part in detail. Note that parts 2,3,4 will be present in both the signature and the header. This is important for preventing replay attacks.

The strings above are concatenated into a single string (in order) separated by spaces.
Important
Any empty elements should be omitted as done in the Python example here:
- The byte sequence is then signed using the
API Keygenerated earlier.
- The final step is to take the generated signature and to Base64 encode it.
- The
Authorizationheader has the following form:
TPV1-HMAC-SHA256 ApiKey={} Nonce={} Timestamp={} Signature={}
Where TPV1-HMAC-SHA256 is a fixed string identifying the protocol. ApiKey, Nonce and Timestamp have to match the values that were signed in steps 1 - 3 above.
- The request can now be sent together with the
Authorizationheader above.
Proxy Server for HMAC requests
These code samples implement proxy servers in Python, Java, and C# to demonstrate the use of the HMAC signature scheme for a real application.
In other sections of this Taurus documentations, we assume you are able to run at least one of these samples to make sure authentication requirements are handled for other workflows.
Postman Pre-request script
A Pre-request Script that can be used in the Postman graphical API workbench tool. Place the following script in the Pre-request Script section of your Postman Taurus-PROTECT setup, and make sure to store a valid apiKey and apiSecret in the Postman Vault. Requires a recent version of Postman, so please make sure to keep your client up-to-date.