Skip to main content
For complete implementation guides, code examples, and troubleshooting, see the Authentication Guide in Getting Started.

​
Overview

The HopNow API uses HMAC-SHA256 signatures to authenticate all requests. Every API request must include four authentication headers.

​
Required Headers

HeaderDescription
X-API-KeyYour API key identifier (public)
X-SignatureHMAC-SHA256 signature of the request
X-TimestampUnix timestamp when request was created
X-NonceUnique random token (32 hex characters)

​
Signature Format

The signature is created by hashing the following payload with your API secret: 
{METHOD}{URL}{TIMESTAMP}{NONCE}{BODY}
Components:
  • METHOD: Uppercase HTTP method (GET, POST, PATCH, DELETE)
  • URL: Complete URL including protocol, domain, path, and query parameters
  • TIMESTAMP: Unix timestamp as string
  • NONCE: Unique 32-character hex string (prevents replay attacks)
  • BODY: JSON request body as string (empty string for GET/DELETE)

​
Quick Example

import hmac
import hashlib
import time
import secrets

def create_signature(method, url, timestamp, nonce, body, api_secret):
    payload = f"{method.upper()}{url}{timestamp}{nonce}{body}"
    signature = hmac.new(
        api_secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return signature

# Usage
timestamp = str(int(time.time()))
nonce = secrets.token_hex(16)
signature = create_signature(
    "POST",
    "https://apis.hopnow.io/v1/customers/cus_123/accounts",
    timestamp,
    nonce,
    '{"name":"My Account"}',
    "your_api_secret"
)

​
Security Requirements

  • Timestamp validation: Requests older than 5 minutes are rejected
  • Nonce uniqueness: Each nonce can only be used once within the 5-minute window
  • HTTPS only: All requests must use HTTPS
  • Keep secrets secure: Never expose your API secret in client-side code or logs

Full Authentication Guide

For complete implementation examples, how to get API keys, security best practices, error handling, and troubleshooting, see the comprehensive Authentication Guide.