Overview
The HopNow API uses HMAC (Hash-based Message Authentication Code) signatures to authenticate requests. This method ensures that:- Requests come from a verified source (authentication)
- Request data hasn’t been tampered with (integrity)
- Requests can’t be replayed (protection against replay attacks)
All API endpoints require HMAC authentication. There are no public endpoints.
How HMAC Authentication Works
Each API request must include four authentication headers:| Header | Description |
|---|---|
X-API-Key | Your API Key ID (public identifier) |
X-Signature | HMAC-SHA256 signature of the request |
X-Timestamp | Unix timestamp when the request was created |
X-Nonce | Unique random token to prevent replay attacks |
Creating the Signature
The HMAC signature is created by:- Constructing the payload from request components
- Creating an HMAC-SHA256 hash using your API secret
- Converting to hexadecimal representation
Signature Payload Format
The payload for signing consists of these components concatenated together:- HTTP_METHOD: Uppercase HTTP method (
GET,POST,PATCH,DELETE) - URL: Complete URL including path and query parameters
- TIMESTAMP: Unix timestamp as a string
- NONCE: Unique random token (32 hex characters)
- BODY: Request body as a string (empty string for GET requests)
Step-by-Step Example
Let’s create a signature for this request:Implementation Examples
Python
JavaScript/Node.js
cURL
Authentication Headers Reference
X-API-Key
Your public API key identifier. This is safe to include in client-side code.X-Signature
The HMAC-SHA256 signature of your request, encoded as a lowercase hexadecimal string.X-Timestamp
Unix timestamp indicating when the request was created. Requests older than 5 minutes are rejected.X-Nonce
Unique random token to prevent replay attacks. Must be 32 hexadecimal characters (16 bytes).Security Best Practices
1. Secure Storage
- Store API secrets in environment variables or secure key management systems
- Never hardcode secrets in your application code
- Use different API keys for different environments (development, staging, production)
2. Request Validation
- Always generate a new nonce for each request to prevent replay attacks
- Ensure nonces are cryptographically random (use
secrets.token_hex()in Python orcrypto.randomBytes()in Node.js) - Validate timestamps to prevent replay attacks beyond the nonce window
- Implement request timeouts to avoid hanging requests
- Log authentication failures for security monitoring
3. Error Handling
- Don’t expose authentication details in error messages
- Implement proper retry logic with exponential backoff
- Monitor for unusual authentication patterns
Common Issues and Troubleshooting
Invalid Signature Error
- Incorrect payload construction (ensure format:
{METHOD}{URL}{TIMESTAMP}{NONCE}{BODY}) - Wrong HTTP method case (must be uppercase)
- Missing or incorrect timestamp/nonce
- URL encoding issues
- Incorrect secret key
Timestamp Too Old Error
Nonce Replay Error
Missing Headers Error
X-API-Key, X-Signature, X-Timestamp, X-Nonce) are included in every request.
Testing Your Implementation
Use this test endpoint to verify your authentication implementation:Need help with authentication? Review the examples above or contact support.