身份认证

使用 Bearer Token、API 密钥或 STS 令牌对 API 网关请求进行身份认证。

API 网关支持三种身份认证方式。每个请求必须以下列方式之一提供凭证。

Session Token

适用于用户端请求的标准认证方式。传入登录后获取的会话令牌。

GET /gpu/api/v1/servers HTTP/1.1
Host: instance-api.bitdeer.ai
Authorization: $USER_TOKEN

curl https://instance-api.bitdeer.ai/gpu/api/v1/servers \
-H "Authorization: $USER_TOKEN"

令牌查找顺序（以第一个非空值为准）：

优先级	来源
1	Cookie `User-Token-V1`
2	查询参数 `token`
3	`Authorization` 请求头
4	Cookie `OU-Token-V1`

网关会将令牌与 SSO 服务进行校验。验证成功后，提取用户身份并签发一个内部 JWT，转发给后端服务。

API 密钥（AK/SK 签名）

用于程序化访问。每个请求必须携带三个查询参数：access_key、nonce 和 signature，并在请求头中附带 X-AUTH-TYPE: AK。

GET /gpu/api/v1/servers?access_key=AK_xxx&nonce=1748870400&signature=<HMAC_SHA256> HTTP/1.1
Host: instance-api.bitdeer.ai
X-AUTH-TYPE: AK

签名算法

收集所有请求参数，排除 access_key、nonce 和 signature。
按字母顺序对键排序，并拼接为 key=value&key=value 格式。
追加 nonce 和 api_key 生成待签名消息。
计算 HMAC-SHA256(api_secret, message)。

message   = sorted_params + nonce + api_key
signature = HMAC-SHA256(api_secret, message)

nonce 必须为 Unix 时间戳（秒）。时间戳与服务器时钟相差超过 30 秒的请求将被拒绝。

NONCE=$(date +%s)
# 先根据参数、nonce 和 api_secret 计算 $SIG，然后执行：
curl "https://instance-api.bitdeer.ai/gpu/api/v1/servers?access_key=$AK&nonce=$NONCE&signature=$SIG" \
-H "X-AUTH-TYPE: AK"

获取 Access Key

登录 Bitdeer AI 控制台。
进入 账户 → API 密钥，点击 创建 API 密钥。
复制 Access Key 和 API Secret——Secret 仅显示一次。

STS 令牌（临时安全令牌）

用于委托或跨账户访问的短期凭证。通过 STS-Token 请求头、Cookie 或查询参数传入令牌，网关会自动识别并将认证类型设置为 STS_TOKEN。

GET /gpu/api/v1/servers HTTP/1.1
Host: instance-api.bitdeer.ai
STS-Token: $STS_TOKEN

curl https://instance-api.bitdeer.ai/gpu/api/v1/servers \
-H "STS-Token: $STS_TOKEN"

令牌查找顺序（以第一个非空值为准）：

优先级	来源
1	Cookie `STS-Token`
2	查询参数 `STS-Token`
3	`STS-Token` 请求头

STS 令牌由 STS 令牌服务签发，内含有效期。令牌过期或无效时，将返回 401 Unauthorized，错误码为 ERR_STS_UNAUTHORIZED。

未授权响应

所有认证失败均返回 401 Unauthorized——响应体格式请参见错误说明。

错误码	原因
`ERR_UNAUTHORIZED`	Bearer Token 缺失或无效
`ERR_STS_UNAUTHORIZED`	STS 令牌已过期或无效
`ERR_AUTHTYPE`	当前接口不允许使用该认证类型
`ERR_SIGNATURE`	HMAC 签名不匹配或 nonce 已过期

密钥管理最佳实践

切勿将凭证提交到代码仓库或打包进客户端代码。
通过环境变量或密钥管理服务加载凭证。
使用 AK/SK 时：每次请求使用当前 Unix 时间戳作为 nonce——超过 30 秒的值将被拒绝。
密钥轮换方式：创建新密钥并部署后，再吊销旧密钥。