> ## 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 key 和 secret 对请求签名，通过 GET /v2/token/generate 获取业务 token，然后在 X-BH-TOKEN 请求头中发送该 token。

VelaFi 分两步对 API 请求进行认证。首先，你的服务器使用 **API key** 和 **API secret** 对请求签名，并调用 `GET /v2/token/generate` 获取**业务 token**。然后，在之后每个需要认证的请求中，通过 `X-BH-TOKEN` 请求头发送该 token。API key 本身绝不能放在 `X-BH-TOKEN` 中。

| 请求头 | 值 | 发送场景 |
| - | - | - |
| `X-BH-APIKEY` | 你的 API key | 仅 `GET /v2/token/generate` |
| `X-BH-TOKEN` | `GET /v2/token/generate` 返回的 token | 其他所有需要认证的请求 |

切勿在任何请求头或参数中发送 API secret。它只保存在你的服务器上，仅用于计算 token 请求的 `signature` 查询参数。

## 开始之前

获取 token 之前，你需要满足以下全部三个条件：

* **已开通 API 访问。** VelaFi 必须为你的账户开通 API 访问权限。在开通之前，token 请求会以错误码 `-5033` 失败。
* **API key 和 API secret。** 在 VelaFi 控制台的 **API Management** 页面创建。参见[创建 API Key](https://docs.velafi.com/cn/docs/guides/creating-api-key.md)。
* **为 key 配置 IP 白名单。** 未配置任何白名单 IP 地址的 key 无法获取 token（错误码 `-1023`）。请添加将要调用 API 的服务器的公网 IP 地址。

## 第 1 步 — 获取 Token

使用 API secret 对字符串 `timestamp=<ms>` 进行签名（HMAC-SHA256，小写十六进制），然后在 `X-BH-APIKEY` 请求头中携带 API key 调用 `GET /v2/token/generate`：

```bash 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/^.*= //')

curl --request GET \
  --url "https://api-test.velafi.com/v2/token/generate?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
  --header "X-BH-APIKEY: ${API_KEY}"
```

成功的响应包含 token 及其过期时间：

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "token": "00000000-0000-0000-0000-000000000006",
    "expireTime": "1740568725231"
  }
}
```

## 第 2 步 — 发送 Token

在每个需要认证的请求中，将 token 放入 `X-BH-TOKEN` 请求头：

```http theme={null}
X-BH-TOKEN: your_token
```

**示例 — 使用 curl 发送已认证的 GET 请求**

```bash theme={null}
curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "X-BH-TOKEN: your_token"
```

完整的 token 请求参考请参见[生成 Token](https://docs.velafi.com/cn/api-reference/generate-token.md)。

## Token 有效期

每个 token 都会过期。token 响应中的 `expireTime` 字段是以毫秒为单位的 Unix 时间戳形式的过期时间。请在该时间之前申请新的 token。使用已过期或未知 token 的请求会以错误码 `-1022` 失败。

## 认证错误

认证失败时返回 HTTP 状态码 `400`。响应体中的 `code` 字段为负数，用于标识具体问题：

```json theme={null}
{
  "code": -1022,
  "msg": "Signature for this request is not valid."
}
```

| 错误码 | 返回场景 | 含义 |
| - | - | - |
| `-1002` | Token 请求 | `X-BH-APIKEY` 请求头缺失或格式错误。 |
| `-1002` | API 调用 | `X-BH-TOKEN` 请求头缺失。 |
| `-1004` | Token 请求 | 缺少 `signature` 查询参数，或在发送其他查询参数时缺少 `timestamp`。`msg` 会指明缺失的参数。 |
| `-1103` | Token 请求 | 请求没有任何查询参数，或只有 `signature` 一个参数。 |
| `-1022` | Token 请求 | 签名不匹配，或 API key 不存在。 |
| `-1022` | API 调用 | token 无效或已过期。请申请新的 token。 |
| `-1023` | Token 请求或 API 调用 | 该 API key 未配置 IP 白名单。 |
| `-2015` | Token 请求 | API key 或你的账户已被禁用，或请求 IP 地址不在该 key 的白名单中。 |
| `-2015` | API 调用 | API key 已被禁用或删除，或你的账户已被禁用。 |
| `-2019` | API 调用 | 请求 IP 地址不在该 key 的白名单中。 |
| `-5033` | Token 请求 | 你的账户未开通 API 访问。请联系 VelaFi。 |

## 沙盒环境与生产环境密钥

> [tab] 沙盒环境
>
> 在开发和 QA 阶段，将**沙盒密钥**与测试 base URL 搭配使用：
>
> ```
> Base URL: https://api-test.velafi.com
> Token:    GET https://api-test.velafi.com/v2/token/generate
> Header:   X-BH-TOKEN: your_sandbox_token
> ```
>
> 沙盒环境中的交易不会转移真实资金。你可以放心地使用它来探索 API、测试边界情况，并在上线前端到端验证你的集成。

> [tab] 生产环境
>
> 仅在集成完成并验证通过后，才将**生产密钥**与正式 base URL 搭配使用：
>
> ```
> Base URL: https://api.velafi.com
> Token:    GET https://api.velafi.com/v2/token/generate
> Header:   X-BH-TOKEN: your_production_token
> ```
>
> 生产环境请求会发起真实的金融交易。请像保管加密私钥一样谨慎保管你的生产密钥。

> [!WARNING]
>
> 切勿将沙盒环境凭证用于生产 URL，也不要将生产凭证用于沙盒环境 URL。请在配置中将两套凭证分开管理。

## 安全最佳实践

遵循以下实践来保护你的 API key，并在发生泄露时尽量降低风险。

> [accordion] 切勿在客户端代码中暴露密钥
>
> API key、API secret 和 token 只能在服务端代码中使用。不要将它们嵌入浏览器 JavaScript、移动应用二进制文件、公开代码仓库或任何终端用户可访问的环境中。请使用环境变量或密钥管理服务（例如 AWS Secrets Manager、HashiCorp Vault 或 GCP Secret Manager）在运行时注入密钥。

> [accordion] 定期轮换密钥
>
> 制定密钥轮换策略（例如每 90 天一次），即使你没有理由怀疑密钥已泄露。在 API Management 页面创建新密钥，为其添加 IP 白名单，将系统切换到新密钥，然后删除旧密钥。

> [accordion] 配置 IP 白名单
>
> IP 白名单是必需的。未配置白名单的 key 无法获取 token（错误码 `-1023`）。来自不在白名单中的 IP 地址的 token 请求会以错误码 `-2015` 失败，来自此类地址的 API 调用会以错误码 `-2019` 失败。请将白名单限制为调用 API 的服务器。
>
> 要进行设置，请在 VelaFi 控制台中打开 **API Management**，然后在对应的 key 上选择 **Whitelist**。每个 key 最多可添加 5 个 IPv4 或 IPv6 地址。请逐个输入地址；不支持 CIDR 网段。

> [accordion] 监控异常使用
>
> 记录系统发出的每个 token 请求和 API 调用，并对非预期的调用发出告警。如果发现可疑活动，请在 API Management 页面删除该 key，创建新的 key，并联系 VelaFi 支持团队。


## Related topics

- [简介](https://docs.velafi.com/cn/docs/introduction.md)
- [错误码](https://docs.velafi.com/cn/docs/error-codes.md)
- [商户](https://docs.velafi.com/cn/docs/merchants.md)
- [获取账户详情](https://docs.velafi.com/cn/api-reference/account/get-account-details.md)
- [生成令牌](https://docs.velafi.com/cn/api-reference/generate-token.md)


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