Skip to content

Authentication and request signing

Each API request is signed with a private key that only you hold. This page explains the moving parts. For working code, see the API quick start.

The two headers

Every request to https://api.hexsafe.hextrust.com/v1 needs:

Header Value
X-API-Key Your API key. It always starts with hsk_.
Authorization Bearer <token>, where the token is a JWT you sign for this request.

Your keys

  • Private key: stays on your systems and signs every token. Hex Trust never sees it.
  • Public key: goes to Hex Safe inside the CSR when you create the API key. Hex Safe uses it to check your signatures.

Supported key types are RSA (2048 or 4096 bits) and ECDSA (P-256, P-384 or P-521).

The token

The bearer token is a JWT with these claims:

Claim What to put in it
api-key Your API key.
uri The path you're calling, including /v1, for example /v1/validate.
nonce A random integer.
exp When the token expires, as a Unix timestamp.
digest POST and PUT requests only: a hash of the request body (see below).

Sign the token with your private key. The API documentation's examples use ES256 with an ECDSA P-256 key and RS256 with an RSA key.

The body digest

For POST and PUT requests, the token must also carry a digest of the exact body you send:

  1. Serialise the body as compact JSON, with no extra spaces or line breaks.
  2. Hash it with SHA-512.
  3. Encode the hash with URL-safe base64.

Send exactly the same compact JSON string as the request body. If the body changes after you sign, the digest won't match.

Common mistakes

  • The uri claim doesn't match the request. It must be the same path you call, with /v1.
  • The token has expired. Check your server's clock, and the exp you set.
  • The body was reformatted after signing. Sign and send the same compact JSON string.
  • The user behind the key doesn't have the right role. The request is authenticated but refused with 403. See Errors and rate limits.

The Authorisation Header and Digest pages of the API documentation have examples in Go, Node, Swift and Python.