组织令牌管理

概述

组织访问令牌（在后端中也称为 OrganizationAccessToken）支持服务器到服务器调用和设备客户端接入，而无需存储用户凭据。令牌继承其颁发者的组织范围，其访问级别由附加的 AccessConfig 确定。

• 基础路径: /api/v2/organization/tokens/

端点摘要

方法	路径	描述	备注
GET	/api/v2/organization/tokens/	列出为活跃组织颁发的所有令牌	见列出令牌。
POST	/api/v2/organization/tokens/	创建新令牌，可选过期时间和项目范围	见创建令牌。
PUT/PATCH	/api/v2/organization/tokens/{id}/	更新令牌元数据（name、is_active、expires_at、access_config）	见更新令牌。
DELETE	/api/v2/organization/tokens/{id}/	永久撤销令牌	见删除令牌。

端点

列出令牌

检索与 request.organization 中的组织关联的所有访问令牌。

GET /api/v2/organization/tokens/
Authorization: Bearer <owner_token>

[
    {
        "id": 12,
        "name": "数据点导出管道",
        "token": "rjm9czn9...",
        "is_active": true,
        "expires_at": "2024-12-31T23:59:59Z",
        "created_at": "2024-01-08T10:00:00Z",
        "last_used_at": "2024-02-15T02:00:00Z",
        "access_config": {
            "role": "manager",
            "all_projects": false,
            "projects": ["prd-greenhouse", "prd-coldroom"]
        }
    }
]

创建令牌

POST /api/v2/organization/tokens/
Authorization: Bearer <owner_token>
Content-Type: application/json

{
    "name": "Webhook 中继",
    "expires_at": "2024-12-31T23:59:59Z",
    "access_config": {
        "role": "operator",
        "projects": ["prd-greenhouse"]
    }
}

字段	类型	必填	描述
name	string	是	用于审计的人类可读标签
expires_at	ISO 8601 字符串	否	Null 产生永不过期的令牌
access_config.role	string	否	默认为 readonly；允许的值：readonly、operator、manager
access_config.all_projects	boolean	否	如果为 true，授予对每个项目的访问权限
access_config.projects	list[string]	否	当 all_projects=false 时的显式项目 ID

响应镜像列表负载，包含生成的 token 和时间戳。安全存储令牌值；创建后无法检索。

更新令牌

PATCH /api/v2/organization/tokens/{token_id}/
Authorization: Bearer <owner_token>
Content-Type: application/json

{
    "name": "Webhook 中继（已弃用）",
    "is_active": false,
    "access_config": {
        "role": "readonly",
        "projects": []
    }
}

支持的字段与创建负载匹配。使用此端点轮换权限或禁用已泄露的令牌，而无需删除它们。

删除令牌

DELETE /api/v2/organization/tokens/{token_id}/
Authorization: Bearer <owner_token>

如果令牌存在且已被撤销，则返回 HTTP 204。下游服务应在令牌被删除后检测 401/403 响应。

错误代码

状态	代码	描述
401	UNAUTHORIZED	缺少或无效的所有者凭据
403	FORBIDDEN	调用者不是组织所有者
404	TOKEN_NOT_FOUND	令牌 ID 不属于该组织
400	BAD_REQUEST	验证错误（例如，重复的名称、无效的过期时间）

操作说明

1. 令牌轮换: 在颁发替换令牌之前使用 PATCH 将 is_active 设置为 false。这避免了客户端迁移期间的停机时间。
2. 最后使用时间戳: 后端在令牌验证 API 调用时自动更新 last_used_at，使陈旧令牌清理成为可能。
3. 访问配置一致性: API 强制执行有效的角色值，并确保 projects 与现有的 project_id 值匹配。具有未知项目的请求将被拒绝，返回 400 BAD_REQUEST。
4. 安全性: 像对待密码一样对待令牌。将它们存储在密钥管理器中，避免将它们嵌入到公开发布的固件中。