身份验证

API 密钥身份验证

所有 API 请求必须在 Authorization 请求头中使用 Bearer 令牌方案包含您的 API 密钥：

Authorization: Bearer flp_your_api_key_here

创建 API 密钥

在您的 FloopFloop 控制台中导航至 Account → API Keys以创建和管理 API 密钥。

• 每个账户最多可拥有 5 个有效 API 密钥
• 密钥仅在创建时显示一次 — 请妥善保存
• 可随时在控制台中撤销密钥
• 所有密钥均以前缀 flp_ 开头

密钥安全

• 切勿共享您的 API 密钥或将其提交到版本控制系统
• 在应用程序中使用环境变量存储密钥
• 定期轮换密钥并撤销未使用的密钥
• 每个密钥拥有独立的速率限制配额

速率限制

API 端点针对每个 API 密钥设有以下速率限制：

速率限制信息包含在响应头中：X-RateLimit-Remaining 和 X-RateLimit-Reset。

验证身份

GET /api/v1/user/me

使用此端点确认您的 API 密钥有效。它将返回已认证用户的个人资料， 是每个官方 SDK 以及 CLI 中 floop whoami命令所使用的 标准“验证身份”调用。

curl https://floopfloop.com/api/v1/user/me \
  -H "Authorization: Bearer flp_your_api_key_here"

响应 (200)：

{
  "data": {
    "id": "user_abc123",
    "email": "you@example.com",
    "name": "Your Name",
    "role": "user",
    "source": "api_key"
  }
}

• role — 普通账户为 "user"，平台员工为 "admin"。
• source — 请求的认证方式。编程凭证为 "api_key"，设备授权 CLI 流程为 "cli_token"。

此处返回 401 UNAUTHORIZED 表示密钥缺失、 已被撤销或格式错误。返回 403 FORBIDDEN 表示 账户存在但缺少限制 API 访问所需的 Business 计划 （详见 API 概览中的前提条件）。

通过 API 管理密钥

大多数用户通过控制台创建密钥，但同一接口也可通过 API 调用， 用于编排场景 — 例如从 CI 作业轮换密钥、列出密钥以审计 使用情况，或在无需打开 UI 的情况下撤销泄露的密钥。这与 CLI 中floop keys list/create/remove 的功能相同。

列出 API 密钥

GET /api/v1/api-keys

返回账户上每个有效（未撤销）密钥的元数据。明文密钥材料不会返回 — 仅返回 keyPrefix（密钥前 8 个十六进制字符，带 flp_ 前缀）。

{
  "data": {
    "keys": [
      {
        "id": "key_abc",
        "name": "ci-deploy",
        "keyPrefix": "flp_a1b2c3d4",
        "scopes": null,
        "lastUsedAt": "2026-04-24T18:30:00Z",
        "createdAt": "2026-04-01T12:00:00Z"
      }
    ]
  }
}

创建 API 密钥

POST /api/v1/api-keys

{
  "name": "ci-deploy"    // required, 1-100 chars
}

响应 (201)：

{
  "data": {
    "id": "key_xyz",
    "rawKey": "flp_a1b2c3d4…full-40-hex…",
    "keyPrefix": "flp_a1b2c3d4"
  }
}

rawKey 仅显示一次— 后续读取只返回 keyPrefix。请立即保存。每个账户最多5 个有效密钥；达到上限时请求将返回409 LIMIT_EXCEEDED— 请先撤销一个未使用的密钥。

创建密钥需要 Business 计划。来自非 Business 账户的请求将返回403 FORBIDDEN，消息为 “Creating API keys requires the Business plan”。平台管理员可绕过此限制。

撤销 API 密钥

DELETE /api/v1/api-keys/{keyId}

将密钥的 id（如 key_xyz）作为路径参数传入。 密钥将立即失效 — 已在工作线程上处理中的请求可能完成， 但不会有新请求通过认证。

响应 (200)：

{ "data": { "success": true } }

• 禁止自我撤销。使用发起请求的同一密钥调用 DELETE 将返回 400 VALIDATION_ERROR— 这可防止 CLI 在调用过程中断开自身连接。请使用其他密钥或从控制台撤销。
• 未知或已撤销的密钥返回 404 NOT_FOUND。

官方 SDK 的 apiKeys.remove() 辅助方法可接受 id 或密钥名称， 在客户端通过列表调用将名称解析为 id。API 本身仅接受 id。

已撤销的密钥无法恢复；请创建新密钥替代。撤销记录将显示在Account → API Keys 的审计日志中。