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

前提条件


分步设置

1

申请 API 访问权限

API 访问权限默认未开通。请联系 VelaFi 团队为您的账户开通。发送邮件至 contact@velafi.com,或通过联系表单提交申请。请附上您的账户邮箱以及对预期集成的简要说明。VelaFi 会在您的账户开通 API 访问权限后进行确认。在此之前,令牌请求将失败并返回代码 -5033。
2

启用双重身份验证(2FA)

如果尚未启用 2FA,平台会在您尝试创建 API 密钥时提示您启用。请在继续之前启用,以免中断。登录您的账户,进入安全设置以开启 2FA。
未启用 2FA 时无法创建 API 密钥。请在继续之前完成此步骤。
3

进入 API 管理

登录后,从控制台菜单中打开 API Management,或访问 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 密钥和密钥密文

请立即复制这两个值,并将其存储在安全的位置。
您的 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 密钥或令牌也是如此。
请将生产服务器的静态 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 之前申请新令牌。
对于带有请求体的请求,大多数端点还要求提供 Content-Type: application/json。

示例:获取令牌并调用 API

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

生产环境与沙盒环境

请为每个环境使用单独的 API 密钥。切勿在测试环境中使用生产密钥,反之亦然。
沙盒环境密钥和生产环境密钥是不同的凭证。准备正式上线时,请在生产账户设置中生成新的 API 密钥,并相应地更新集成配置。