Security Gates

Overview

In addition to HMAC signature verification, the EASYCRED API gateway enforces two additional security gates to prevent replay attacks and request tampering: Timestamp Drift and Nonce Replay protection.

Timestamp Drift Gate

The gateway compares the x-timestamp header value against the server’s current UTC time. If the difference exceeds ±300 seconds (5 minutes), the request is rejected:

| T_server - T_request | > 300 seconds  →  401 Unauthorized

Why this matters: Even if an attacker intercepts a valid signed request, they cannot re-send it more than 5 minutes later — the signature will be rejected as stale.

Valid Window

Requests with x-timestamp within ±300 seconds of server time are accepted.

Outside Window → 401

Requests older than 5 minutes or with future timestamps beyond 5 minutes are rejected.

Keep your server clock synchronized using NTP (Network Time Protocol). Clock drift is the most common cause of unexpected 401 errors in production.

Nonce Replay Gate

Every request must include a unique x-nonce value. The gateway stores all nonces seen within the drift window in a distributed Redis cache. If a request arrives with a nonce that has already been used within the window, it is immediately rejected:

Duplicate nonce within drift window  →  401 Replayed request rejected

Why this matters: Even within the 5-minute timestamp window, an attacker cannot replay an intercepted request because the nonce is already “used up”.

Nonce Requirements

Requirement	Details
Format	Printable ASCII characters
Length	1–200 characters
Uniqueness	Must be unique per request
Recommended	UUID v4 (e.g., `94fc6cee-137c-4206-bb0a-48623bd0847c`)

Combined Protection Model

Both gates work together to provide layered security:

Incoming Request
      │
      ├── ✓ Valid HMAC Signature?
      │         └── No → 401 Bad Signature
      │
      ├── ✓ Timestamp within ±300s?
      │         └── No → 401 Stale Timestamp
      │
      ├── ✓ Nonce not seen before?
      │         └── No → 401 Replayed Request
      │
      └── ✓ All gates passed → Request processed

Troubleshooting

Error	Likely Cause	Fix
`401 Stale timestamp`	Server clock drift	Sync clock with NTP
`401 Replayed request`	Nonce reused across retries	Generate a fresh UUID per request attempt
`401 Bad signature`	Signing string built incorrectly	Verify canonical string construction, especially the empty body `""` for GET requests

Getting Started

API Integration

Partner Portal

Overview

Timestamp Drift Gate

Valid Window

Outside Window → 401

Nonce Replay Gate

Nonce Requirements

Combined Protection Model

Troubleshooting

​Overview

​Timestamp Drift Gate

Valid Window

Outside Window → 401

​Nonce Replay Gate

​Nonce Requirements

​Combined Protection Model

​Troubleshooting

Overview

Timestamp Drift Gate

Nonce Replay Gate

Nonce Requirements

Combined Protection Model

Troubleshooting