ApiKeyService

API Key 管理服务，用于创建和管理下游 API 访问密钥。API Key 可用于程序化访问 RustBill gRPC 接口，通过 ApiKeyAuthLayer 中间件认证，注入 DownstreamUser。

RPC 列表

RPC	描述	权限
CreateApiKey	创建新的 API Key（密钥仅返回一次）	admin 或已授权 customer
ListApiKeys	列出指定客户的 API Key 列表	admin 或已授权 customer
RevokeApiKey	吊销（禁用）API Key	admin 或 API Key 所属客户

CreateApiKey

描述

创建新的 API Key。返回的 api_key 字段仅在创建时返回一次，之后无法再次获取，客户端应立即安全保存。

Request — `CreateApiKeyRequest`

字段	类型	编号	必填	描述
name	string	1	是	Key 名称（便于识别）
customer_id	string	2	是	关联客户 ID（admin 需指定，customer 用户自动设置）

Response — `CreateApiKeyResponse`

字段	类型	编号	描述
api_key	string	1	完整 API Key（仅此一次返回，需立即保存）
key_prefix	string	2	Key 前缀（用于识别，如 `"rk_live_a1b2c3"`）
id	string	3	API Key 记录 ID（UUID）

错误码

错误	说明
InvalidArgument	名称不能为空
NotFound	指定客户不存在
PermissionDenied	当前用户无权为此客户创建 Key（customer 需 `can_create_api_keys=true`）

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"name":"生产环境 API Key","customer_id":"0192a123-..."}' \
  localhost:50051 rustbill.downstream.ApiKeyService/CreateApiKey

const resp = await api.createApiKey({
  name: "生产环境 API Key",
  customer_id: "0192a123-..."
});
// resp.api_key → "rk_live_a1b2c3d4e5f6..." (仅此一次)
// resp.key_prefix → "rk_live_a1b2c3"
// resp.id → "0192b456-..."
// 立即安全存储 api_key，之后无法再获取

ListApiKeys

描述

列出指定客户的所有 API Key（不包含完整密钥值，仅含前缀和元数据）。

Request — `ListApiKeysRequest`

字段	类型	编号	必填	描述
customer_id	string	1	是	客户 ID（UUID）

Response — `ListApiKeysResponse`

字段	类型	编号	描述
keys	repeated ApiKeyInfo	1	API Key 信息列表

ApiKeyInfo

字段	类型	编号	描述
id	string	1	Key 记录 ID（UUID）
key_prefix	string	2	Key 前缀（如 `"rk_live_a1b2c3"`）
name	string	3	Key 名称
enabled	bool	4	是否启用
created_at	string	5	创建时间（RFC3339）
last_used_at	string	6	最近使用时间（RFC3339）
expires_at	string	7	过期时间（RFC3339）

错误码

错误	说明
PermissionDenied	非管理员且无此客户的 API Key 管理权限

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"customer_id":"0192a123-..."}' \
  localhost:50051 rustbill.downstream.ApiKeyService/ListApiKeys

const resp = await api.listApiKeys({
  customer_id: "0192a123-..."
});
// resp.keys → [{ id, key_prefix, name, enabled, created_at, last_used_at, expires_at }]

RevokeApiKey

描述

吊销（禁用）指定的 API Key。吊销后该 Key 无法再用于认证。

Request — `RevokeApiKeyRequest`

字段	类型	编号	必填	描述
id	string	1	是	API Key 记录 ID（UUID）

Response — `RevokeApiKeyResponse`

无字段。

错误码

错误	说明
NotFound	API Key 不存在
PermissionDenied	非管理员且非该 Key 所属客户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"id":"0192b456-...}' \
  localhost:50051 rustbill.downstream.ApiKeyService/RevokeApiKey

const resp = await api.revokeApiKey({
  id: "0192b456-..."
});

API Key 使用方式

API Key 在 HTTP 请求中作为 Bearer token 携带：

Authorization: Bearer rk_live_a1b2c3d4e5f6...

认证成功后，ApiKeyAuthLayer 中间件在 request extensions 中注入 DownstreamUser：

DownstreamUser {
    api_key_id: Uuid,
    customer_id: Uuid,
    permissions: Vec<String>
}

服务端通过 require_downstream() 守卫访问下游用户信息，并根据 customer_id 自动限定数据范围。

权限对照

操作	Admin	Customer（can_create_api_keys=true）	Customer（can_create_api_keys=false）
CreateApiKey	可创建任意客户	仅创建自身客户	禁止
ListApiKeys	可查看任意客户	仅查看自身客户	禁止
RevokeApiKey	可吊销任意 Key	仅吊销自身 Key	禁止

安全注意事项

api_key 完整值仅在 CreateApiKey 响应中返回一次，服务端不存储明文密钥（仅存哈希）
API Key 应存储在安全的环境中（如环境变量、密钥管理服务）
建议定期轮换 API Key（创建新 Key + 吊销旧 Key）
吊销操作将 enabled 设为 false，不物理删除记录

Keyboard shortcuts

RustBill 文档