Documentation Index
Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
Use this file to discover all available pages before exploring further.
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.
How HMAC Authentication Works
Each API request must include four authentication headers:| Header | Description |
|---|---|
X-API-Key | Your API Key ID |
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 API key identifier used to identify your account.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.