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 within a small amount of time)
  • additionalData - Optional additional data (used for DELETE subscription requests)

​
Timestamp Requirements

  • Must be current Unix timestamp (seconds, not milliseconds)
  • Requests with expired or future timestamps will be 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

​
Endpoints

MethodPathDescription
GET/subscriptionGet user’s active subscription
DELETE/subscriptionCancel one or more subscriptions
See Endpoint Reference for detailed documentation.