/v0/insto/custody/ with the headers and signature described below. First, create a Custody API user and obtain its API key and Base64-encoded secret.
API Users and Access Control
API users function similarly to human users in that they are assigned roles, permissions, and vault access at the time of creation. When an API user interacts with the system, these settings are enforced to control which data they can access and which actions they can perform. However, unlike regular users, API users cannot log in to the Custody application. Their interaction with the system is limited strictly to API calls, making them an essential component for programmatic access while maintaining strict security boundaries.Creating a new API Key
A system administrator must initiate the creation of a new API user before generating an API key:- Log in to your Custody environment
- Navigate to Settings → Users → API Users
- Submit a request for a new API user and complete the two-factor authentication (2FA) process
- The request will appear under Tasks → Pending until it is approved by the Admin Quorum
- Once approved, open the request details to view the API key information
- The admin user who submitted the request can access the API key and secret from the API key details page
Authentication headers
Send these headers with each authenticated v0 request:
Keep the secret on your client. Use it to calculate the signature; send only the
public key and signature in the request headers.
The nonce belongs in the
api-nonce header. You do not need to add a nonce field
to a v0 JSON body. Generate nonces consistently across every process that shares
the key, and continue the key’s existing sequence when migrating from a legacy
endpoint. A millisecond timestamp is suitable for a single request; concurrent
requests need coordinated nonce generation so values do not repeat or arrive out
of order.
Calculate the signature
Use the exact request target and body you will send:- Take the complete path and query string, including
/v0/insto/custody/, and preserve their URL encoding and query parameter order. Exclude the scheme, host, and HTTP method. - Append the exact request body bytes to the ASCII-encoded
api-noncevalue and calculate their SHA-256 digest. Keep the raw 32-byte digest. - Append that digest to the UTF-8-encoded path and query string.
- Calculate HMAC-SHA512 over those bytes using your Base64-decoded API secret.
- Base64-encode the HMAC result and send it as
api-sign.
body_bytes is empty. For JSON requests,
serialize the body once, sign those UTF-8 bytes, and send the same bytes with
Content-Type: application/json. Changing whitespace or property order after
signing changes the signature.
Request examples
SetKRAKEN_CUSTODY_API_KEY and KRAKEN_CUSTODY_API_SECRET in your environment.
These examples list vaults with an empty GET body.
- Python
- Node.js
Verify your implementation
Use this fixed test vector to check your signature calculation offline. The secret is an example value, and the nonce is fixed for this check. Use your own credentials and a fresh nonce for API requests.
The expected
api-sign is:
Migrating legacy authentication
Legacy/0/private/* requests carry nonce in the request body. Sign the legacy
path and the complete encoded body required by that endpoint, including its
nonce field.
For v0 requests, send api-nonce as a header and sign the complete v0 path and
query string. Follow the legacy method mapping
for the replacement routes.