> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an API Key

> Enable API access, create your API key and secret, whitelist your server IPs, and use them to get the token you send in the X-BH-TOKEN header.

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

* An active VelaFi account. See [Create Your VelaFi Account](https://docs.velafi.com/docs/guides/creating-account.md) if you haven't signed up yet.
* At least one merchant created and KYC/KYB verified. See [Create and Verify a Merchant](https://docs.velafi.com/docs/guides/creating-merchant.md).

***

## 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](mailto:contact@velafi.com) or submit a request using the [Contact Form](https://share.hsforms.com/1P1po-MZAThupnwug_qDEEAr8y9l). 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.

> [!WARNING]
>
> 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](https://www.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.

> [!WARNING]
>
> **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.

> [!TIP]
>
> 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`.

```http theme={null}
X-BH-TOKEN: <your-token>
```

Most endpoints also require `Content-Type: application/json` for requests with a body.

```http theme={null}
X-BH-TOKEN: <your-token>
Content-Type: application/json
```

### Example: Get a Token and Call the API

The following example gets a token and uses it to fetch your account details.

```bash cURL theme={null}
API_KEY="<your-api-key>"
API_SECRET="<your-api-secret>"
TIMESTAMP=$(( $(date +%s) * 1000 ))
SIGNATURE=$(printf 'timestamp=%s' "$TIMESTAMP" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.*= //')

# 1. Get a token
curl -X GET "https://api.velafi.com/v2/token/generate?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
  -H "X-BH-APIKEY: ${API_KEY}"

# 2. Call the API with the token from data.token
curl -X GET "https://api.velafi.com/v2/user/account" \
  -H "X-BH-TOKEN: <your-token>"
```

```python Python theme={null}
import hashlib
import hmac
import time

import requests

BASE_URL = "https://api.velafi.com"
API_KEY = "<your-api-key>"
API_SECRET = "<your-api-secret>"

# 1. Get a token
timestamp = str(int(time.time() * 1000))
signature = hmac.new(
    API_SECRET.encode("utf-8"),
    f"timestamp={timestamp}".encode("utf-8"),
    hashlib.sha256,
).hexdigest()
token_body = requests.get(
    f"{BASE_URL}/v2/token/generate",
    params={"timestamp": timestamp, "signature": signature},
    headers={"X-BH-APIKEY": API_KEY},
).json()
if token_body["code"] != 200:
    raise RuntimeError(f"Token request failed: {token_body}")

# 2. Call the API with the token
response = requests.get(
    f"{BASE_URL}/v2/user/account",
    headers={"X-BH-TOKEN": token_body["data"]["token"]},
)
print(response.json())
```

```javascript Node.js theme={null}
const crypto = require("crypto");

const BASE_URL = "https://api.velafi.com";
const API_KEY = "<your-api-key>";
const API_SECRET = "<your-api-secret>";

async function main() {
  // 1. Get a token
  const timestamp = Date.now().toString();
  const signature = crypto
    .createHmac("sha256", API_SECRET)
    .update(`timestamp=${timestamp}`)
    .digest("hex");
  const tokenResponse = await fetch(
    `${BASE_URL}/v2/token/generate?timestamp=${timestamp}&signature=${signature}`,
    { headers: { "X-BH-APIKEY": API_KEY } }
  );
  const tokenBody = await tokenResponse.json();
  if (tokenBody.code !== 200) {
    throw new Error(`Token request failed: ${JSON.stringify(tokenBody)}`);
  }

  // 2. Call the API with the token
  const response = await fetch(`${BASE_URL}/v2/user/account`, {
    headers: { "X-BH-TOKEN": tokenBody.data.token },
  });
  console.log(await response.json());
}

main();
```

***

## Production vs. Sandbox Environments

Use separate API keys for each environment. Never use a production key in your test environment, or vice versa.

| Environment | Base URL |
| - | - |
| Production | `https://api.velafi.com` |
| Sandbox | `https://api-test.velafi.com` |

> [!NOTE]
>
> 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.


## Related topics

- [Create an Account](https://docs.velafi.com/docs/guides/creating-account.md)
- [Introduction](https://docs.velafi.com/docs/introduction.md)
- [Quickstart](https://docs.velafi.com/docs/quickstart.md)
- [Create a Webhook](https://docs.velafi.com/api-reference/webhooks/create-webhook-endpoints.md)
- [Authentication](https://docs.velafi.com/api-reference/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.