General - utilsio

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:

Header	Description
`X-utilsio-Timestamp`	Unix timestamp in seconds when the signature was created
`X-utilsio-Signature`	HMAC-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:

Header	Value	Meaning
`Cache-Control`	`public, max-age=300`	Cache for 5 minutes
`ETag`	Version identifier	Used for cache validation

Error Handling

All error responses include a success: false flag and an error string:

{
  "success": false,
  "error": "Error message"
}

Common Errors:

Error	Cause
`X-utilsio-Signature and X-utilsio-Timestamp headers are required`	Missing signature or timestamp header
`appId is required`	Missing appId query parameter
`Invalid or expired timestamp`	Timestamp outside of accepted window
`Invalid signature`	Signature doesn’t match computed value

​Overview

​Authentication

​Signing Requirements

​Signing Logic

​Timestamp Requirements

​CORS Headers

​Caching

​Error Handling

Overview

Authentication

Signing Requirements

Signing Logic

Timestamp Requirements

CORS Headers

Caching

Error Handling