身份验证

TeamDay API 使用个人访问令牌 (PAT) 进行身份验证。所有 API 请求必须在 Authorization 标头中包含有效令牌。

获取访问令牌

第 1 步：生成令牌

在 cc.teamday.ai 登录您的 TeamDay 账户
导航至设置 → API 访问
点击生成新令牌
可选择设置自定义过期时间（7-365 天，默认值：90 天）
立即复制您的令牌 - 您将无法再次看到它！

第 2 步：安全存储

您的令牌将如下所示：

td_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdE

令牌格式：

前缀：td_（识别 TeamDay 令牌）
长度：前缀后 43 个字母数字字符
编码：Base64url（URL 安全）

存储在环境变量中：

# Unix/Linux/macOS
export TEAMDAY_TOKEN="td_your-actual-token-here"

# Windows (PowerShell)
$env:TEAMDAY_TOKEN="td_your-actual-token-here"

# 或在 .env 文件中（用于本地开发）
TEAMDAY_TOKEN=td_your-actual-token-here

使用令牌

在 Authorization 标头中包含您的令牌，带有 Bearer 方案：

Authorization: Bearer td_your-actual-token-here

示例请求

列出代理：

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

创建代理：

curl -X POST https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "role": "Research and analysis",
    "systemPrompt": "You are a helpful research assistant.",
    "visibility": "private"
  }'

获取执行详情：

curl https://cc.teamday.ai/api/v1/executions/exec_123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

令牌安全功能

静态加密

令牌受企业级安全保护：

哈希： SHA-256 哈希存储在数据库中（不可逆）
加密： 用于令牌元数据的 AES-256-GCM 加密
无纯文本存储： 创建后原始令牌永远不会存储

自动验证

每个 API 请求都验证：

令牌格式 - 正确的前缀和长度
哈希查找 - 令牌存在于数据库中
过期 - 令牌未过期
组织范围 - 用户属于组织
最后使用跟踪 - 在每个请求上更新

范围界定

每个令牌的范围为：

用户： 令牌属于特定用户（创建者）
组织： 继承用户的组织成员资格
权限： 使用用户的角色和权限

重要： 令牌继承创建它们的用户的权限。如果用户的访问被撤销，他们的令牌将立即停止工作。

令牌管理

查看活跃令牌

在设置 → API 访问中查看所有活跃令牌：

令牌名称（可选标签）
创建日期
最后使用时间戳
过期日期
权限范围

撤销令牌

立即撤销令牌：

转至设置 → API 访问
在列表中找到令牌
点击撤销
确认删除

何时撤销：

令牌泄露或暴露
团队成员离开组织
不再需要令牌
轮换凭据（安全最佳实践）

令牌过期

默认过期： 90 天

自定义过期：

最小值：7 天
最大值：365 天

过期时会发生什么：

API 请求返回 401 Unauthorized
错误消息："Token expired"
令牌自动清理（软删除）

自动续订： 不支持。在过期前生成新令牌。

错误响应

缺少令牌

请求：

curl https://cc.teamday.ai/api/v1/agents

响应：

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Authorization header required"
}

无效令牌

请求：

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer invalid_token"

响应：

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

过期令牌

请求：

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer td_expired_token"

响应：

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Token expired"
}

安全最佳实践

要做的事情 ✅

将令牌存储在环境变量中 - 永远不要在源代码中硬编码
为每个集成使用单独的令牌 - 更容易跟踪和撤销
设置适当的过期日期 - 对于高风险环境更短
定期轮换令牌 - 特别是对于生产系统
如果泄露立即撤销 - 宁可安全也不要后悔
仅使用 HTTPS - 永远不要通过纯 HTTP 发送令牌
监控令牌使用情况 - 定期检查"最后使用"时间戳

不要做的事情 ❌

永远不要将令牌提交到 Git - 对 .env 文件使用 .gitignore
永远不要共享令牌 - 每个集成应有其自己的令牌
永远不要记录令牌 - 从应用程序日志中编辑
永远不要在 URL 参数中发送 - 仅使用标头
永远不要跨环境重用 - 开发/预备/生产应具有单独的令牌
永远不要存储在客户端代码中 - 令牌仅用于服务器端使用

环境变量示例

# .env（添加到 .gitignore！）
TEAMDAY_TOKEN=td_your-actual-token-here

# 代码中的使用
const token = process.env.TEAMDAY_TOKEN

const response = await fetch('https://cc.teamday.ai/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})

令牌轮换策略

建议的轮换计划：

开发： 90 天（默认）
暂存： 60 天
生产： 30 天
高安全性： 7 天

如何在不停机的情况下轮换：

生成新令牌（尚未撤销旧令牌）
更新应用程序以使用新令牌
部署并验证新令牌是否有效
监控 24-48 小时（检查旧令牌使用情况）
确认未使用后撤销旧令牌

速率限制

当前状态： 未强制执行速率限制

最佳实践：

为重试实现指数退避
在适当时缓存响应
使用合理的请求率（建议 < 100 req/min）

未来： 可能会引入速率限制。我们将提供提前通知和文档。

OAuth（即将推出）

计划的功能：

对第三方集成的 OAuth 2.0 支持
范围内的权限（只读、写入、管理员）
组织级 API 密钥

跟踪 OAuth 进度 →

测试令牌

快速测试：

# 应返回代理列表（或空数组）
curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# 成功响应（示例）
[
  {
    "id": "agent_123",
    "name": "My Agent",
    "role": "Assistant",
    "createdAt": "2025-12-09T12:00:00Z"
  }
]

如果您看到 401 Unauthorized：

验证令牌复制正确（没有额外空格）
检查令牌在设置 → API 访问中未过期
确认用户仍然有组织访问权限
尝试生成新令牌

需要帮助？

令牌不起作用？

检查错误参考用于故障排除
验证格式：td_ + 43 个字符
确认在仪表板中未过期

有问题吗？

📧 电子邮件：[email protected]
💬 Discord：加入社区

最后更新： 2025 年 12 月 9 日