> ## 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.

# 创建 API 密钥

> 开通 API 访问权限，创建您的 API 密钥和密钥密文（Secret），将服务器 IP 加入白名单，并使用它们获取在 X-BH-TOKEN 请求头中发送的令牌。

您的 VelaFi API 密钥（API Key）和 API 密钥密文（API Secret）是您的服务器用于从 `GET /v2/token/generate` 获取业务令牌的凭证。在每个请求的 `X-BH-TOKEN` 请求头中发送的是该令牌，而不是密钥。在获取令牌之前，VelaFi 必须为您的账户开通 API 访问权限，必须启用双重身份验证（2FA），并且密钥必须配置 IP 白名单。本指南将逐步引导您完成每个步骤。

## 前提条件

* 一个有效的 VelaFi 账户。如果您尚未注册，请参阅[创建您的 VelaFi 账户](https://docs.velafi.com/cn/docs/guides/creating-account.md)。
* 至少已创建一个商户，并已完成 KYC/KYB 验证。请参阅[创建并验证商户](https://docs.velafi.com/cn/docs/guides/creating-merchant.md)。

***

## 分步设置

**1. 申请 API 访问权限**

API 访问权限默认未开通。请联系 VelaFi 团队为您的账户开通。

发送邮件至 [contact@velafi.com](mailto:contact@velafi.com)，或通过[联系表单](https://share.hsforms.com/1P1po-MZAThupnwug_qDEEAr8y9l)提交申请。请附上您的账户邮箱以及对预期集成的简要说明。

VelaFi 会在您的账户开通 API 访问权限后进行确认。在此之前，令牌请求将失败并返回代码 `-5033`。

**2. 启用双重身份验证（2FA）**

如果尚未启用 2FA，平台会在您尝试创建 API 密钥时提示您启用。请在继续之前启用，以免中断。

登录您的账户，进入安全设置以开启 2FA。

> [!WARNING]
>
> 未启用 2FA 时无法创建 API 密钥。请在继续之前完成此步骤。

**3. 进入 API 管理**

登录后，从控制台菜单中打开 **API Management**，或访问 [velafi.com/security/interface](https://www.velafi.com/security/interface)。

您可以在此创建、查看和管理所有 API 密钥及 IP 白名单。

**4. 创建您的 API 密钥**

在 API 管理页面点击 **Create API Key** 按钮。

在 **Notes** 字段中输入 1–30 个字符的描述性标签——例如 `Production Integration`。该字段为必填项。此标签可帮助您日后识别该密钥的用途。

点击 **Continue**，然后输入您的 2FA 验证码进行确认。**API Key Created** 窗口会显示您的 **Api Key** 和 **Api Secret**。

**5. 复制并存储您的 API 密钥和密钥密文**

请立即复制这两个值，并将其存储在安全的位置。

> [!WARNING]
>
> **您的 API 密钥密文（API Secret）仅显示一次。** API 密钥会一直显示在您的密钥列表中，但密钥密文不会再次显示。如果您丢失了密钥密文，请删除该密钥并创建一个新密钥。

请遵循以下存储最佳实践：

* **不要**将 API 密钥存储在明文文件、版本控制系统或任何公开位置。
* **要**使用密码管理器或密钥管理工具（例如 AWS Secrets Manager、HashiCorp Vault 或 1Password）安全地存储密钥。
* **不要**通过 Slack、电子邮件或其他消息平台分享您的 API 密钥。

每个 API 密钥都是唯一的，并授予对您账户生产环境的访问权限。

**6. 配置 IP 白名单**

为密钥添加 IP 白名单。此步骤为必需步骤：没有白名单的密钥无法获取令牌（代码 `-1023`）。

在 API 管理页面，选择该密钥上的 **Whitelist**，输入将调用 API 的服务器的公网 IP 地址，并使用您的 2FA 验证码确认。每个密钥最多可添加 5 个 IPv4 或 IPv6 地址。请逐个输入地址；不接受 CIDR 范围。来自任何其他 IP 地址的请求都会被拒绝，即使使用有效的 API 密钥或令牌也是如此。

> [!TIP]
>
> 请将生产服务器的静态 IP 地址加入白名单。如果您在本地测试，可以临时添加您自己的 IP，但请在正式上线前将其移除。

白名单可确保即使密钥泄露，攻击者也无法从未知位置使用该密钥。

***

## 使用您的 API 密钥

您的服务器使用 API 密钥和密钥密文获取令牌，然后在 `X-BH-TOKEN` 请求头中发送该令牌：

1. 构造字符串 `timestamp=<ms>`，其中 `<ms>` 为当前的 Unix 时间（毫秒）。以您的 API 密钥密文作为密钥计算其 HMAC-SHA256，并将结果编码为小写十六进制。
2. 在 `X-BH-APIKEY` 请求头中携带您的 API 密钥，调用 `GET /v2/token/generate?timestamp=<ms>&signature=<signature>`。
3. 在每个请求的 `X-BH-TOKEN` 请求头中发送返回的 `token`。请在 `expireTime` 之前申请新令牌。

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

对于带有请求体的请求，大多数端点还要求提供 `Content-Type: application/json`。

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

### 示例：获取令牌并调用 API

以下示例获取令牌并使用它查询您的账户详情。

```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();
```

***

## 生产环境与沙盒环境

请为每个环境使用单独的 API 密钥。切勿在测试环境中使用生产密钥，反之亦然。

| 环境 | 基础 URL |
| - | - |
| 生产环境 | `https://api.velafi.com` |
| 沙盒环境 | `https://api-test.velafi.com` |

> [!NOTE]
>
> 沙盒环境密钥和生产环境密钥是不同的凭证。准备正式上线时，请在生产账户设置中生成新的 API 密钥，并相应地更新集成配置。


## Related topics

- [创建账户](https://docs.velafi.com/cn/docs/guides/creating-account.md)
- [VelaFi API 文档](https://docs.velafi.com/cn/index.md)
- [简介](https://docs.velafi.com/cn/docs/introduction.md)
- [认证](https://docs.velafi.com/cn/api-reference/authentication.md)
- [快速开始](https://docs.velafi.com/cn/docs/quickstart.md)


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