How a Boxis API request is signed

How a request is signed

Every call is a POST to https://api.boxis.net/. The secret never travels. It only produces the signature.

Headers

Send the raw JSON body and these headers. X-Boxis-Key is the public id. X-Boxis-Consumer is the account authorization. X-Boxis-Method and X-Boxis-Path are the granted route, not the HTTP verb of the POST. X-Boxis-Timestamp is unix seconds. X-Boxis-Signature is the lowercase hex HMAC-SHA256.

X-Boxis-Key: bxk_...
X-Boxis-Consumer: bxu_...
X-Boxis-Method: GET
X-Boxis-Path: /sms/timestamp
X-Boxis-Timestamp: 1727450000
X-Boxis-Signature: hex hmac-sha256
Content-Type: application/json

Canonical string

Join these five lines with a newline. Hash the exact bytes you send. Sign that string with HMAC-SHA256 and the secret.

{account authorization}
{METHOD}
https://api.boxis.net{path}
{unix timestamp}
{sha256 of the raw body}

A space, a different key order in the JSON, or a trailing newline changes the hash and the signature no longer matches.

Route and body

The JSON body selects the section and the command. Unknown fields are ignored. The signed method and path must be granted on the key, and they must be the route of that command. A mismatch is HTTP 403. A reserved section is HTTP 501.

{"section":"/sms","command":"getAPITimestamp"}

Time, IP, limits

The timestamp must fall within 5 minutes. The same signature is refused a second time.
api.boxis.net records the caller address. If the key has an IP list, any other address is HTTP 401. The caller cannot choose that address.
Too many requests return HTTP 429. Repeated authentication failures can block the source address for a while.
A revoked, expired, or year-unused key is rejected on the next request.

Response

Success is HTTP 201 for sendSMS and HTTP 200 for the other live commands. The body is result, message and data. An error body is code and message. The reference lists each code.