Skip to content

API quick start

This guide covers the steps in Hex Safe to get API access. For endpoints, request formats and code examples, see our API documentation. You need a terminal with OpenSSL, and a Hex Safe user who can create API keys.

The API's base URL is https://api.hexsafe.hextrust.com/v1.

1. Decide which user the key belongs to

An API key has no permissions of its own. It has exactly the same access as the user who creates it, through that user's roles. The API documentation recommends separate API users:

  • a viewer, for read-only actions;
  • a signer, for transactions.

Ask an Admin to add the user with only the roles it needs.

2. Create a key pair and a CSR

On your own machine, generate a private key and a certificate signing request (CSR). For example, with ECDSA:

# Private key: keep this file secret, Hex Trust never sees it
openssl ecparam -genkey -name prime256v1 -out my_ecdsa.pem

# CSR: this is what you paste into Hex Safe
openssl req -key ./my_ecdsa.pem -new -out my_ecdsa.csr \
  -subj "/C=HK/O=Your Company/CN=yourcompany.com"

Supported keys are RSA (2048 or 4096 bits) and ECDSA (P-256, P-384 or P-521). The API documentation has the RSA commands too.

3. Create the API key

In Hex Safe, go to Settings › API Key, click Create API Key, and paste the contents of my_ecdsa.csr. See Create and manage API keys for an interactive walkthrough.

Your new key starts with hsk_. Use the eye icon in the list to reveal it, or the copy icon to copy it.

4. Make your first call

Every request needs two headers:

Header Value
X-API-Key Your API key (hsk_...)
Authorization Bearer followed by a JWT you sign with your private key

To build and sign these, follow the code examples in our API documentation. It is the reference for every endpoint, request and response.

To check that your key and signing work before you build anything else, call GET /v1/validate. A 200 response means they're working. If you get 401, see Authentication and request signing and Errors and rate limits.

5. Next steps