Skip to main content
It is recommended to use one of our official SDKs for the best support and ease of integration.

​
Overview

  • Base URL: https://utilsio.dev/api/v1
  • Authentication: HMAC-SHA256 signatures
  • Content Type: application/json

​
Authentication

All requests must be cryptographically signed using your App Secret. This signature-based authentication ensures that:
  • Requests originate from your application (not a third party)
  • Request data has not been tampered with
  • Requests are recent

​
Signing Requirements

Every request requires two headers:
HeaderDescription
X-utilsio-TimestampUnix timestamp in seconds when the signature was created
X-utilsio-SignatureHMAC-SHA256 signature over the message

​
Signing Logic

The signature is computed over a message in this format: 
${deviceId}-${appId}-${timestamp}${additionalData ? `-${additionalData}` : ""}
Where:
  • deviceId - The device ID associated with the request
  • appId - Your Application ID (from query parameter)
  • timestamp - Unix timestamp in seconds (must be within a small allowable skew)
  • additionalData - Optional additional data (used for DELETE subscription requests)

​
Timestamp Requirements

  • Must be the current Unix timestamp in seconds (not milliseconds).
  • Requests with expired or future timestamps are rejected with 401 Unauthorized.

​
CORS Headers

The API supports CORS with the following headers: 
Access-Control-Allow-Origin: <request-origin>
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-utilsio-Signature, X-utilsio-Timestamp
Access-Control-Allow-Credentials: true
Preflight requests (OPTIONS) are automatically handled.

​
Caching

Some endpoints return cache headers:
HeaderValueMeaning
Cache-Controlpublic, max-age=300Cache for 5 minutes
ETagVersion identifierUsed for cache validation

​
Error Handling

All error responses include a success: false flag and an error string: 
{
  "success": false,
  "error": "Error message"
}
Common Errors:
ErrorCause
X-utilsio-Signature and X-utilsio-Timestamp headers are requiredMissing signature or timestamp header
appId is requiredMissing appId query parameter
Invalid or expired timestampTimestamp outside of accepted window
Invalid signatureSignature doesn’t match computed value
Last modified on January 28, 2026