Skip to main content
Your VelaFi API key and API secret are the credentials your server uses to get a business token from 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


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.
You cannot create an API key without 2FA enabled. Complete this step before continuing.
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.
Your API secret is shown only once. The API key stays visible in your key list, but the secret is not displayed again. If you lose the secret, delete the key and create a new one.
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.
Each API key is unique and grants access to the production environment on your account.
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.
Use your production server’s static IP address for the whitelist. If you are testing locally, you can temporarily add your own IP, but remove it before going live.
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 the X-BH-TOKEN header:
  1. 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.
  2. Call GET /v2/token/generate?timestamp=<ms>&signature=<signature> with your API key in the X-BH-APIKEY header.
  3. Send the returned token in the X-BH-TOKEN header on each request. Request a new token before expireTime.
Most endpoints also require 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.