API 参考

密钥

通过 API 列出、创建、更新和删除项目密钥。值是只写的 — 永远不会以明文返回。

最后更新： 2026年6月6日

Secrets API

管理项目密钥 — API 密钥、令牌及其他凭证，您已部署的项目将在运行时通过 process.env 读取这些值。密钥值为只写：通过这些端点写入，并通过已部署项目的运行时输出，任何 API 响应中均不会返回这些值。

有关密钥工作原理及存储方式的背景信息，请参阅 Secrets & Environment Variables 指南。

列出密钥

GET /api/v1/projects/{projectId}/secrets

返回项目上定义的密钥集合。仅返回密钥名称、值的后四位字符及时间戳。

响应：

{
  "data": {
    "secrets": [
      {
        "key": "STRIPE_SECRET_KEY",
        "lastFour": "aB3x",
        "createdAt": "2026-04-18T09:12:44.000Z",
        "updatedAt": "2026-04-21T15:03:10.000Z"
      }
    ]
  }
}

创建或更新密钥

POST /api/v1/projects/{projectId}/secrets

{ "key": "STRIPE_SECRET_KEY", "value": "sk_live_..." }

以 (projectId, key)为幂等键 — 重复提交相同密钥将覆盖已存储的值。更新操作不计入每项目的密钥数量上限；仅添加新密钥时才计数。

密钥格式：UPPER_SNAKE_CASE，1–64 个字符，必须以字母开头。值长度：1–4096 个字符。

响应：

{
  "data": {
    "secret": {
      "key": "STRIPE_SECRET_KEY",
      "lastFour": "aB3x",
      "createdAt": "2026-04-18T09:12:44.000Z",
      "updatedAt": "2026-04-21T15:03:10.000Z"
    }
  }
}

删除密钥

DELETE /api/v1/projects/{projectId}/secrets/{key}

删除密钥。幂等操作 — 删除不存在的密钥仍返回success: true，existed 字段指示是否实际删除了记录。

响应：

{ "data": { "success": true, "existed": true } }

错误

400 VALIDATION_ERROR — 请求体格式错误、密钥不符合格式要求，或值为空或超过 4096 个字符。
404 NOT_FOUND — 项目不存在或调用方的 API 密钥未绑定到该项目。对于写入/删除操作，调用方还必须在所属团队中拥有admin 角色。
409 SECRET_LIMIT_EXCEEDED — 项目已有 25 个密钥。请删除一个或更新现有密钥，而非添加新密钥。
429 RATE_LIMITED — 超出 API 速率限制。详情请参阅 Error Handling。