API Keys

API key 是身份验证令牌，可让你从外部工具、脚本或以编程方式集成中访问 Almirant。它们是连接 Claude Code 等 MCP 客户端、CI/CD 自动化，或任何需要与 Almirant API 交互的服务的主要机制。

用途

API key 主要用于：

• 连接 Claude Code -- 对 Almirant MCP 服务器进行身份验证，使 Claude Code 能够管理项目、看板和工作项。有关详细信息，请参阅 MCP 身份验证指南。
• 自动化 -- 创建工作项、更新状态或记录 AI 会话的 CI/CD 脚本或 pipeline。
• 自定义集成 -- 与 Almirant API 交互的自有应用。

生成 API key

1. 前往 设置 > API Keys。
2. 点击 生成新的 API Key。
3. 输入描述性名称以标识该 key 的用途（例如：“Claude Code - 工作笔记本电脑”、“CI/CD Pipeline”、“内部机器人”）。
4. 选择该 key 所拥有的权限。
5. 点击 创建。
6. 立即复制 API key。

现在复制 key

完整 API key 只会在创建时显示一次。如果未复制就关闭对话框，则无法恢复它，必须生成新的 key。

使用 API key

API key 使用 Bearer 方案在 Authorization header 中发送：

curl -H "Authorization: Bearer tu-api-key-aqui" \
  https://api.almirant.ai/api/projects

用于 MCP（Claude Code）的配置

要在 Claude Code 中将 API key 用于 Almirant MCP 服务器，请将以下配置添加到项目的 .mcp.json 文件：

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=uuid-del-proyecto",
      "headers": {
        "Authorization": "Bearer tu-api-key-aqui"
      }
    }
  }
}

对于本地开发，请将 URL 替换为 http://localhost:3001/mcp?projectId=uuid-del-proyecto。

有关更多配置选项，请参阅完整的 MCP 身份验证和 Project Scoping参考文档。

管理 API key

查看现有 key

通过 设置 > API Keys，可以查看所有已生成 key 的列表，其中包括：

字段	描述
名称	创建 key 时分配的描述性名称
前缀	用于识别 key 的首字符（其余部分隐藏）
创建日期	生成 key 的时间
上次使用	使用该 key 的上次已验证请求日期

撤销 API key

如果 API key 已泄露或不再需要：

1. 前往 设置 > API Keys。
2. 在列表中找到该 key。
3. 点击 撤销。
4. 确认撤销。

危险

撤销 API key 会立即生效且不可逆。任何使用该 key 的服务或工具都会立即停止工作。撤销前请确保更新受影响服务的配置。

安全最佳实践

API key 安全

API key 可访问你的组织数据。请以与密码相同的安全级别对待它们。

• 每个服务一个 key -- 为每个工具或服务生成不同的 API key。如果其中一个泄露，可以将其撤销而不影响其他服务。
• 描述性名称 -- 使用可清楚说明 key 使用位置的名称：“Claude Code - 办公室 PC”、“GitHub Actions - Deploy”、“Slack Bot - 通知”。
• 不要共享 key -- 每位需要 MCP 访问权限的团队成员都应生成自己的 API key。
• 不要在代码中包含 key -- 永远不要将 API key commit 到代码仓库。请使用环境变量或 secrets manager。
• 定期检查 -- 撤销不再使用或用途不明的 key。
• 轮换已泄露的 key -- 如果怀疑 key 已泄露，请立即撤销并生成新的 key。

使用环境变量的安全示例

不要将 key 直接写入配置文件：

# .env (excluido de git via .gitignore)
ALMIRANT_API_KEY=tu-api-key-aqui

// .mcp.json (usa referencia a variable de entorno si tu herramienta lo soporta)
{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${ALMIRANT_API_KEY}"
      }
    }
  }
}

开发者指南

身份验证架构

API key 以哈希形式存储在数据库 schema 的 apiKeys 表中。身份验证流程为：

1. 客户端在 Authorization: Bearer <key> header 中发送 API key。
2. 后端在 apiKeys 表中查找已哈希的 key。
3. 如果 key 有效，则获取关联的用户和组织。
4. 身份验证上下文（{ user, organizationId }）会注入到请求中。
5. 受保护路由使用此上下文按组织筛选数据。

相关 endpoint

方法	路由	描述
GET	/api/api-keys	列出组织的 API key
POST	/api/api-keys	生成新的 API key
DELETE	/api/api-keys/:id	撤销 API key

权限和 scope

API key 继承创建该 key 的用户权限。key 的 scope 仅限于该用户的组织。