GET /v2/token/generate. You send that token, not the key, in the X-BH-TOKEN header of each request. Before you can get a token, VelaFi must enable API access on your account, two-factor authentication (2FA) must be on, and the key must have an IP whitelist. This guide walks you through each step.
Prerequisites
- An active VelaFi account. See Create Your VelaFi Account if you haven’t signed up yet.
- At least one merchant created and KYC/KYB verified. See Create and Verify a Merchant.
Step-by-Step Setup
1
Request API Access
API access is not enabled by default. Contact the VelaFi team to activate it for your account.Email contact@velafi.com or submit a request using the Contact Form. Include your account email and a brief description of your intended integration.VelaFi will confirm once API access has been activated on your account. Until then, token requests fail with code
-5033.2
Enable Two-Factor Authentication (2FA)
If 2FA is not already active, the platform will prompt you to enable it when you attempt to create an API key. Enable it before proceeding to avoid interruptions.Log in to your account and navigate to your security settings to turn on 2FA.
3
Navigate to API Management
After logging in, open API Management from the dashboard menu, or go to velafi.com/security/interface.This is where you create, view, and manage all your API keys and IP whitelists.
4
Create Your API Key
Click the Create API Key button on the API Management page.Enter a descriptive label of 1–30 characters in the Notes field — for example,
Production Integration. The field is required. This label helps you identify the key’s purpose later.Click Continue, then enter your 2FA code to confirm. The API Key Created window shows your Api Key and Api Secret.5
Copy and Store Your API Key and Secret
Copy both values immediately and store them in a secure location.Follow these storage best practices:
- Do not store your API key in plaintext files, version control, or any public location.
- Do use a password manager or secrets management tool (such as AWS Secrets Manager, HashiCorp Vault, or 1Password) to store the key securely.
- Do not share your API key in Slack, email, or other messaging platforms.
6
Configure Whitelisted IP Addresses
Add an IP whitelist to the key. This step is required: a key with no whitelist cannot get a token (code
-1023).On the API Management page, select Whitelist on the key, enter the public IP addresses of the servers that will call the API, and confirm with your 2FA code. You can add up to 5 IPv4 or IPv6 addresses per key. Enter each address individually; CIDR ranges are not accepted. Requests from any other IP address are rejected, even with a valid API key or token.Whitelisting ensures that a compromised key cannot be used by an attacker from an unknown location.Using Your API Key
Your server uses the API key and secret to get a token, then sends the token in theX-BH-TOKEN header:
- Build the string
timestamp=<ms>, where<ms>is the current Unix time in milliseconds. Compute its HMAC-SHA256 with your API secret as the key, and hex-encode the result in lowercase. - Call
GET /v2/token/generate?timestamp=<ms>&signature=<signature>with your API key in theX-BH-APIKEYheader. - Send the returned
tokenin theX-BH-TOKENheader on each request. Request a new token beforeexpireTime.
Content-Type: application/json for requests with a body.
Example: Get a Token and Call the API
The following example gets a token and uses it to fetch your account details.Production vs. Sandbox Environments
Use separate API keys for each environment. Never use a production key in your test environment, or vice versa.Sandbox keys and production keys are different credentials. When you are ready to go live, generate a new API key under your production account settings and update your integration’s configuration accordingly.

