创建 API Key

POST/web/v1/workspaces/{workspaceId}/api-keysJWT

为指定工作空间创建新的 API Key。响应中包含 API Key 密钥，该密钥仅在创建时返回一次。客户端必须安全存储该密钥，之后无法再次获取。

鉴权

Auth Chain: WEB Chain — 需要 Authorization: Bearer <jwt> 需要工作空间 OWNER 角色。 以下请求头由系统自动注入（前端无需处理）： X-PORTAL-ACCESS-CODE (Nginx)、X-Request-Id (Gateway)

请求参数

Name	Type	Required	In	Description
workspaceId	string	Yes	path	工作空间业务 ID
name	string	Yes	body	API Key 显示名称（1-128 个字符）
scopes	string[]	No	body	API 权限范围代码列表，用于限制访问权限。如果为空，该密钥没有任何访问权限。
mode	integer	No	body	密钥模式：`1` = LIVE（默认），`2` = TEST（沙箱）。仅 PARTNER Portal 可创建 TEST 密钥。
ipWhitelist	string[]	No	body	IP 白名单。支持单个 IP（`192.168.1.100`）和 CIDR 格式（`192.168.1.0/24`）。为空表示不限制 IP。

成功响应

已创建201

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "apiKeyId": "sk_live_abc123",
    "secret": "sk_live_**********",
    "name": "Production Key",
    "status": "ACTIVE",
    "mode": "LIVE",
    "scopes": [
      "payment:read",
      "payment:write"
    ],
    "ipWhitelist": [
      "192.168.1.0/24"
    ],
    "createdAt": "2026-03-21T00:00:00Z"
  }
}

错误响应

未授权401

{
  "success": false,
  "code": "4010",
  "message": "Invalid or expired token"
}

禁止访问 — 非工作空间所有者403

{
  "success": false,
  "code": "4030",
  "message": "Only workspace owner can manage API keys"
}

说明

• secret 字段仅在创建时返回一次。 之后无法再次获取，请提示用户立即保存。
• 仅工作空间 OWNER 可创建 API Key。
• Consumer Portal 密钥默认为 LIVE 模式；TEST 模式创建仅限 PARTNER Portal。