Label Studio Access Tokens 完全指南Personal Access Token 与 Legacy Token 的认证体系解析【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio导读Label Studio 提供两类用于调用 HTTP API 与 Python SDK 的认证凭证——Personal Access TokenPAT个人访问令牌与 Legacy Token旧版令牌二者常被统称为 API keys。本指南以 access_tokens.md 为主线结合label_studio/jwt_auth模块的源码实现完整讲解两类令牌的定位差异、组织级开关配置、SDK/HTTP API 两种调用方式下的使用细节以及 PAT 背后的 JWT 刷新机制与安全特性帮助你正确选择并安全使用 Label Studio 的访问令牌。两类访问令牌Personal Access Token 与 Legacy Token在 Label Studio 中access tokens访问令牌与 API keysAPI 密钥是同一个概念可以互换使用。目前平台同时存在两类令牌它们在生命周期、可见性、认证方式上有着本质区别对比维度Personal Access TokenPATLegacy Token有效期TTL可在组织级别设置Label Studio Enterprise 专属能力永不过期可见性创建后仅向用户展示一次一直保留在账号设置中可随时查看底层实现JWT 刷新令牌refresh token传统静态令牌吊销方式支持手动吊销支持手动吊销HTTP API 使用需要额外步骤先用 PAT 换取短期 access token无需刷新直接使用HTTP API 请求头-H Authorization: Bearer token-H Authorization: Token tokenSDK 使用只需设置一次只需设置一次两类令牌在 Python SDK 中的使用方式完全相同差异主要体现在 HTTP API 的请求头与认证流程上详见下文。从源码看该令牌体系由独立的 Django 应用jwt_auth承载其 URL 路由定义在 label_studio/jwt_auth/urls.pyapi/jwt/settings—— 组织级 JWT/令牌开关设置api/token/—— 当前用户的令牌列表与创建GET/POSTapi/token/refresh/—— 用 refresh token 换取新的 access tokenapi/token/blacklist/—— 将 refresh token 加入黑名单吊销api/token/rotate/—— 轮换 refresh token创建新令牌并吊销旧令牌。查找你的访问令牌获取 API 密钥/访问令牌的入口在 Web 界面的右上角点击你的用户图标选择Account Settings账号与设置。如果在Account Settings页面中既看不到Personal Access Tokens页签也看不到Legacy Tokens页签说明你的组织尚未启用对应类型的令牌需要先由组织管理员按下一节说明进行开启。为组织启用访问令牌用户能在Account Settings页面上看到哪些令牌选项取决于组织级别的设置。管理员Admin 与 Owner 角色进入Organization页面选择Settings Access Token Settings即可进行配置。注意Organization 页面仅对 Admin 与 Owner 角色的用户开放Enterprise 版限制。在该设置页可以启用或禁用两类令牌禁用某类令牌后已存在的该类令牌将无法再通过 Label Studio 平台完成认证。这意味着禁用不是简单的隐藏选项而是对存量令牌的即时失效。Personal Access Token Time-to-LiveTTL可为个人访问令牌设置过期时间这是 Label Studio Enterprise 的专属能力。这一组织级开关的底层实现是JWTSettings模型定义在 label_studio/jwt_auth/models.py。每个组织通过AutoOneToOneField关联一份 JWT 设置包含三个关键字段字段默认值说明api_tokens_enabledTrue是否启用 JWT API token即 PAT认证api_token_ttl_days200 * 365约 200 年永不过期PAT 的有效天数Enterprise 可在界面中调整legacy_api_tokens_enabledFalse是否启用 Legacy token 认证对应的读写接口为api/jwt/settings实现见 label_studio/jwt_auth/views.py 的JWTSettingsAPI其请求体与响应体只暴露api_tokens_enabled与legacy_api_tokens_enabled两个字段序列化定义见 label_studio/jwt_auth/serializers.py。需要说明的是源码显示两个开关的默认值存在版本演进当前 models.py 中legacy_api_tokens_enabled默认为False而最早的迁移文件 0001_initial.py 中该字段默认为True、api_tokens_enabled默认为False。也就是说新部署默认以 PATJWT为主Legacy Token 默认关闭。此外组织创建时也可通过环境变量与启动参数控制 Legacy Token 的初始状态见 label_studio/organizations/functions.py环境变量LABEL_STUDIO_ENABLE_LEGACY_API_TOKEN默认False见 label_studio/core/settings/base.py命令行启动参数--enable-legacy-api-token定义见 label_studio/core/argparser.py。测试套件也验证了该开关的生效路径在 label_studio/tests/drafts.tavern.yml 中测试通过向POST /api/jwt/settings发送{legacy_api_tokens_enabled: true}来为组织开启 Legacy Token随后才进行 Legacy 令牌的 API 测试。API keys 与 Access tokens 的关系在 Label Studio 的语境下access tokens 与 API keys 含义相同、可以互换使用。文档、界面文案、SDK 参数如api_key、环境变量LABEL_STUDIO_API_KEY中出现的这些名称指的都是你账号下的这两类令牌。Personal Access TokenPAT详解PAT 的底层是一个JWT refresh token刷新令牌它本身只用于换取访问凭证而非直接作为每次请求的认证凭据。这也解释了为何 PAT 具有可配置 TTL、仅显示一次、支持吊销等特性。SDK 用法使用 Python SDK 时PAT 可以直接写在脚本里也可以通过环境变量LABEL_STUDIO_API_KEY提供# Define the URL where Label Studio is accessible and the API key for your user account LABEL_STUDIO_URL http://localhost:8080 # API key can be either your PAT or legacy access token LABEL_STUDIO_API_KEY your-token # Import the SDK and the client module from label_studio_sdk import LabelStudio # Connect to the Label Studio API client LabelStudio(base_urlLABEL_STUDIO_URL, api_keyLABEL_STUDIO_API_KEY)SDK 客户端会自动完成 PAT 的认证流程因此只需设置一次无需像裸 HTTP API 那样手动刷新。API 密钥的 OpenAPI 认证定义见 label_studio/jwt_auth/auth.py也明确将LABEL_STUDIO_API_KEY环境变量作为api_key的来源。HTTP API 用法先刷新、再携带 Bearer由于 PAT 本质是 JWT refresh token直接将它放进请求头并不能完成认证。正确的流程是用 PAT 通过刷新接口换取一个短期的 access token再用这个 access token 去访问业务 API。第一步用 PAT 发起 POST 请求换取短期 access tokencurl -X POST your-label-studio-url/api/token/refresh \ -H Content-Type: application/json \ -d {refresh: your-personal-access-token}该端点对应源码中的DecoratedTokenRefreshViewlabel_studio/jwt_auth/views.py它继承自rest_framework_simplejwt的标准TokenRefreshView职责是使用 refresh token 获取新的 access token。响应是一个 JSON payload结构与文档描述一致{ access: your-new-access-token }第二步把拿到的 access token 放入Authorization: Bearer请求头调用业务接口curl -X method Label Studio URL/api/endpoint -H Authorization: Bearer your-new-access-token该短期 access token 大约在 5 分钟后过期过期后请求会返回401此时需要再次使用 PAT 调用api/token/refresh获取新凭证。这种短期令牌 手动刷新的机制为 API 调用增加了一层安全防护即便 access token 泄露其有效窗口也很短。在服务端Bearer 认证由JWTAuthenticationMiddlewarelabel_studio/jwt_auth/middleware.py处理中间件先检查Authorization头是否为Bearer前缀且令牌具备 JWT 结构复用 label_studio/jwt_auth/token_format.py 的is_jwt_formatted判断再通过 simplejwt 的JWTAuthentication完成校验并进一步校验组织是否开启了api_tokens_enabled。检查 PAT 过期时间由于 PAT 属于 JWT其过期时间编码在expclaim 中。可以使用pyjwt解码检查# pip install pyjwt from datetime import datetime, timezone import jwt decoded jwt.decode(token) exp decoded.get(exp) token_is_expired (exp datetime.now(timezone.utc).timestamp())需要留意Label Studio 在数据库中只保存 JWT 的 header 与 payload 部分截断掉签名以保护令牌隐私、避免前端拿到完整签名。这一行为由自定义的LSTokenBackend实现label_studio/jwt_auth/models.py令牌类LSAPIToken同时提供get_full_jwt()用于在创建时返回完整令牌label_studio/jwt_auth/models.py。这从源码层面印证了文档所述PAT 仅向用户展示一次创建响应LSAPITokenCreateSerializer返回完整 JWT而列表接口LSAPITokenListSerializer只返回截断形式见 label_studio/jwt_auth/serializers.py。Legacy Token 详解Legacy Token 的安全性总体上不如 PAT原因在于它没有内置过期机制必须依靠手动吊销来失效只要不吊销它就永久有效。SDK 用法Legacy Token 在 Python SDK 中的使用方式与 PAT没有任何区别同样按上文的 SDK 示例传入api_key即可只需设置一次。HTTP API 用法Legacy Token 不需要刷新步骤直接通过Authorization: Token请求头携带注意这与 PAT 的Authorization: Bearer不同curl -X method Label Studio URL/api/endpoint -H Authorization: Token token服务端对应的认证类为TokenAuthenticationPhaseoutlabel_studio/jwt_auth/auth.py它继承 DRF 的TokenAuthentication并在功能开关开启时做两件事若组织已禁用 Legacy Tokenlegacy_api_tokens_enabled为False直接返回401提示该组织已禁用 legacy token 认证——这正对应文档中禁用某类令牌后存量令牌将无法再认证的行为记录一次 Legacy Token 认证的使用日志。另外中间件层还支持X-Api-Key请求头XApiKeySupportMiddlewarelabel_studio/core/middleware.py会将其转换为等价的Authorization头——JWT 格式的密钥映射为BearerLegacy 密钥映射为Token。令牌生命周期管理吊销与轮换虽然原文档只提到可以手动吊销源码进一步揭示了令牌生命周期管理的完整 API 能力均定义在 label_studio/jwt_auth/urls.py 与 label_studio/jwt_auth/views.py创建POST /api/token/LSAPITokenView.perform_create。源码中有一个值得注意的约束如果当前用户已存在有效令牌会抛出TokenExistsError409提示请先吊销现有令牌再创建新令牌label_studio/jwt_auth/views.py 与 L183-L190。列表GET /api/token/仅返回当前用户未过期且未进入黑名单的 refresh tokenlabel_studio/jwt_auth/views.py。吊销黑名单POST /api/token/blacklist/LSTokenBlacklistView将指定 refresh token 加入黑名单使其无法再换取新的 access token返回204令牌无效或已被吊销时返回404L193-L223。轮换POST /api/token/rotate/LSAPITokenRotateView将当前 refresh token 加入黑名单同时为用户签发一个新令牌并返回L226-L269。这些接口共同构成了一套完整的 PAT 生命周期管理能力配合组织级的开关与 TTL 设置可以在不更换账号的前提下灵活控制 API 凭证的生效范围与失效时机。安全建议与最佳实践综合文档与源码实现使用访问令牌时建议遵循以下实践优先使用 Personal Access Token。Legacy Token 永不过期一旦泄露影响面是长期的PAT 即便泄露其短期 access token 也会在约 5 分钟后失效且可配置 TTL、可吊销、可轮换。妥善保存创建时返回的完整令牌。PAT 在创建后仅显示一次数据库中也只保存截断版本不含签名丢失后无法从平台找回只能吊销重建。善用组织级开关。禁用某类令牌会使该类全部存量令牌立即失效适合作为安全事故后的快速止血手段Enterprise 用户还可通过 TTL 强制所有 PAT 定期过期。严格保护Authorization头与LABEL_STUDIO_API_KEY环境变量避免将令牌提交到版本库或写入日志若怀疑泄露通过api/token/blacklist或api/token/rotate及时吊销/轮换。在脚本中优先使用 SDK。SDK 会自动处理 PAT 的认证细节只需设置一次避免在每次请求中手动维护短期 access token 的刷新逻辑。小结Label Studio 的访问令牌体系由JWT 化的 Personal Access Token与传统 Legacy Token双轨构成前者安全属性更强TTL、仅显示一次、JWT 刷新、可吊销后者使用简单直接Authorization: Token。组织管理员可通过Organization Settings Access Token Settings统一管控两类令牌的启用状态与 PAT 有效期而开发者则需根据令牌类型选择对应的 HTTP 请求头BearervsToken或直接依赖 Python SDK 自动处理。如需进一步了解令牌背后的认证实现可深入阅读 label_studio/jwt_auth/ 目录下的 models、views、middleware 与 auth 源码。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考