Overview
The Terminal Gateway uses API key-based authentication for both HTTP and WebSocket protocols. Each protocol has a different authentication mechanism:| Protocol | Authentication Method |
|---|---|
| HTTP API | HMAC-SHA256 signature per request |
| WebSocket API | API key in headers or query parameters at connection time |
API Key Provisioning
API keys are provisioned manually by Modulus Labs. To request API credentials:Contact support
Email support@moduluslabs.io with your integration details.
Provide information
Include your organization name and intended use case (desktop POS, terminal integration, etc.).
HTTP API Authentication
HTTP requests require HMAC-SHA256 signature authentication. Each request must include three authentication headers.Required Headers
| Header | Description |
|---|---|
x-api-key | Your API key |
x-timestamp | ISO 8601 timestamp (must be within 5 minutes of server time) |
x-signature | Base64-encoded HMAC-SHA256 signature |
String-to-Sign Format
Construct the string to sign using this format:METHOD- HTTP method in uppercase (GET,POST)PATH- Request path (e.g.,/v1/terminals)TIMESTAMP- Value ofx-timestampheaderSHA256(BODY)- Hex-encoded SHA256 hash of request body (empty string hash for GET requests)
Signature Computation
Example
For a GET request to/v1/terminals at 2024-01-15T10:30:00.000Z:
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 is the SHA256 hash of an empty string.Code Examples
Common Authentication Errors
| Error Code | HTTP Status | Description | Solution |
|---|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid API key | Verify your API key is correct |
INVALID_SIGNATURE | 401 | HMAC signature verification failed | Check signature computation |
TIMESTAMP_EXPIRED | 401 | Request timestamp outside 5-minute window | Ensure system clock is synchronized |
WebSocket API Authentication
WebSocket connections authenticate during the connection handshake. Provide your API key via headers or query parameters.Authentication via Headers
Include thex-api-key header in your WebSocket connection request:
| Header | Required | Description |
|---|---|---|
x-api-key | Yes | Your API key |
x-group-id | No | Group identifier (optional) |
Authentication via Query Parameter
Alternatively, pass your API key as a query parameter:Code Examples
Security Best Practices
Protect Credentials
Store API keys and secrets in environment variables or a secure secrets manager. Never hardcode them in source code.
Use Headers for WebSocket
Prefer header-based authentication over query parameters to avoid keys appearing in logs and browser history.
Synchronize Time
For HTTP API, ensure your system clock is synchronized with NTP. Timestamps must be within 5 minutes of server time.
Rotate Keys
Rotate API keys periodically and immediately if you suspect compromise. Contact support for key rotation.
Next Steps
HTTP Quick Start
Start integrating with the HTTP API
WebSocket Quick Start
Start integrating with the WebSocket API
Core Concepts
Learn about device enforcement and reconnection resilience
Data Types
Review shared data types and error codes