Authentication: Step-by-Step Walkthrough

Before You Start

To make authenticated requests, you must already have:

• An API Key (provided by Mercury)
• A Secret Key (shared securely during onboarding)

If you do not yet have credentials, contact the Mercury team to complete the provisioning process.

---

Step 1: Generate a Nonce

For each request, generate a unique nonce value.

• The nonce can be any string or number.
• It must be unique per request.
• Common approaches include:
  • A high-precision timestamp
  • A UUID
  • A monotonic counter

We recommend generating a UUID using this online tool or using a high precision timestamp when using a script to generate credentials.

Example

729522b9-88f9-47df-a102-cd8e53e30a5e

---

Step 2: Construct the Data to Sign

The signature is generated from a canonical string built from the request details.

For GET requests

{API_KEY}
{HTTP_METHOD}
{REQUEST_PATH}
{NONCE}

For non-GET requests (POST, PUT, PATCH, DELETE)

{API_KEY}
{HTTP_METHOD}
{REQUEST_PATH}
{REQUEST_BODY}
{NONCE}

• Each value is separated by a newline character (\n)
• The request path must not include the domain (only the path and query string)
• The request body must be exactly as sent (including whitespace and ordering)

Example (GET)

a9F3kL2PqX7WmT8R4N0Bv6HcYzJdE5u
GET
/v1/bookings/12345
729522b9-88f9-47df-a102-cd8e53e30a5e

---

Step 3: Generate the Signature

1. Hash the canonical string using HMAC-SHA256
2. Use your Secret Key as the signing key
3. Base64-encode the result

Result

Tr5YQmM7GD7gFZh8cB2kXfFZ3pB/tuHHkAPlg2zMrpc=

This value becomes your request signature.

---

Step 4: Send the Request with Authentication Headers

Include the following headers with every API request:

Example

x-api-key: a9F3kL2PqX7WmT8R4N0Bv6HcYzJdE5u
x-nonce: 729522b9-88f9-47df-a102-cd8e53e30a5e
Authorization: HMACSHA256 Tr5YQmM7GD7gFZh8cB2kXfFZ3pB/tuHHkAPlg2zMrpc=

---

Step 5: Server Validation

On receipt, the Mercury API will:

1. Validate the API key
2. Ensure the nonce has not been used before
3. Rebuild the canonical string
4. Recompute the HMAC signature
5. Compare it to the provided signature

If all checks pass, the request is authorized and processed.

---

Common Causes of Authentication Failure

• Reusing a nonce
• Including the domain in the signed path
• Signing a request body that differs from what is sent
• Incorrect newline placement
• Using the wrong HTTP method casing

---

Summary

Every request must be:

• Uniquely identified (nonce)
• Cryptographically signed (HMAC-SHA256)
• Fully verifiable by the server

This ensures secure, tamper-proof, and replay-protected access to the API.