Back to Details

access-tokens

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.
<objective>
路由说明：若用户意图不明确，请使用references/intent-clarification.md中的通用澄清模板。
<objective>

Access Tokens

访问令牌

Manage TrueFoundry personal access tokens (PATs). List, create, and delete tokens used for API authentication, CI/CD pipelines, and AI Gateway access.
管理TrueFoundry个人访问令牌（PAT），可列出、创建和删除用于API认证、CI/CD流水线和AI Gateway访问的令牌。

When to Use

使用场景

List, create, or delete personal access tokens for API authentication, CI/CD pipelines, or AI Gateway access.
</objective> <instructions>
当需要列出、创建或删除用于API认证、CI/CD流水线或AI Gateway访问的个人访问令牌时使用。
</objective> <instructions>

Step 1: Preflight

步骤1：前置检查

Run the 
status
skill first to verify 
TFY_BASE_URL
and 
TFY_API_KEY
are set and valid.
When using direct API, set 
TFY_API_SH
to the full path of this skill's 
scripts/tfy-api.sh
. See 
references/tfy-api-setup.md
for paths per agent.
首先运行
status
skill，验证
TFY_BASE_URL
和
TFY_API_KEY
已配置且有效。
使用直接API时，请将
TFY_API_SH
设置为当前skill下
scripts/tfy-api.sh
的完整路径。各Agent对应的路径可查看
references/tfy-api-setup.md
。

Step 2: List Access Tokens

步骤2：列出访问令牌

Via Tool Call

通过工具调用

tfy_access_tokens_list()
tfy_access_tokens_list()

Via Direct API

通过直接API

bash
TFY_API_SH=~/.claude/skills/truefoundry-access-tokens/scripts/tfy-api.sh
bash
TFY_API_SH=~/.claude/skills/truefoundry-access-tokens/scripts/tfy-api.sh

List all personal access tokens

列出所有个人访问令牌

$TFY_API_SH GET /api/svc/v1/personal-access-tokens

Present results:
Personal Access Tokens:
NameIDCreated AtExpires At
ci-pipelinepat-abc2025-01-152025-07-15
dev-localpat-def2025-03-01Never

**Security:** Never display token values. They are only shown once at creation time.
$TFY_API_SH GET /api/svc/v1/personal-access-tokens

结果展示格式：
个人访问令牌:
名称ID创建时间过期时间
ci-pipelinepat-abc2025-01-152025-07-15
dev-localpat-def2025-03-01永不失效

**安全提示：** 永远不要展示令牌值，它们仅在创建时会显示一次。

Step 3: Create Access Token

步骤3：创建访问令牌

Ask the user for a token name before creating.
创建前需先向用户确认令牌名称。

Via Tool Call

通过工具调用

tfy_access_tokens_create(payload={"name": "my-token"})
Note: Requires human approval (HITL) via tool call.
tfy_access_tokens_create(payload={"name": "my-token"})
注意： 需要通过工具调用获得人类审批（HITL）。

Via Direct API

通过直接API

bash
undefined
bash
undefined

Create a new personal access token

创建新的个人访问令牌

$TFY_API_SH POST /api/svc/v1/personal-access-tokens '{"name":"my-token"}'

**IMPORTANT:** The token value is returned ONLY in the creation response.

> **Security: Token Display Policy**
> - Display the token value exactly once from the API creation response so the user can copy it.
> - After displaying, instruct the user to store it in a secure location immediately.
> - The agent must NEVER store, log, or re-display the token value after the initial creation response.
> - If the user asks to see the token again later, instruct them to create a new token.

Present the result:
Token created successfully! Name: my-token Token: <value from API response — shown once>
⚠️ Save this token NOW — it will not be shown again. Store it in a password manager, CI/CD secret store, or TrueFoundry secret group. Never commit tokens to Git or share them in plain text.
undefined
$TFY_API_SH POST /api/svc/v1/personal-access-tokens '{"name":"my-token"}'

**重要提示：** 令牌值仅会在创建的响应中返回一次。

> **安全规则：令牌展示策略**
> - 仅将API创建响应中的令牌值展示一次，方便用户复制
> - 展示后立即提示用户将其存储在安全位置
> - Agent永远不得在初始创建响应之外存储、记录或重新展示令牌值
> - 如果用户后续要求再次查看令牌，告知用户需要创建新的令牌

结果展示格式：
令牌创建成功! 名称: my-token 令牌: <API响应返回的令牌值 — 仅展示一次>
⚠️ 请立即保存该令牌 — 后续不会再展示。 请将其存储在密码管理器、CI/CD密钥存储库或TrueFoundry密钥组中。 永远不要将令牌提交到Git仓库，也不要以明文形式分享。
undefined

Step 4: Delete Access Token

步骤4：删除访问令牌

Ask for confirmation before deleting — this is irreversible and will break any integrations using the token.
删除前需要用户确认操作 — 该操作不可逆，会破坏所有使用该令牌的集成服务。

Via Tool Call

通过工具调用

tfy_access_tokens_delete(id="TOKEN_ID")
Note: Requires human approval (HITL) via tool call.
tfy_access_tokens_delete(id="TOKEN_ID")
注意： 需要通过工具调用获得人类审批（HITL）。

Via Direct API

通过直接API

bash
undefined
bash
undefined

Delete a personal access token

删除个人访问令牌

$TFY_API_SH DELETE /api/svc/v1/personal-access-tokens/TOKEN_ID

</instructions>

<success_criteria>
$TFY_API_SH DELETE /api/svc/v1/personal-access-tokens/TOKEN_ID

</instructions>

<success_criteria>

Success Criteria

成功标准

  • The user can list all personal access tokens in a formatted table
  • The user can create a new token and receives the token value
  • The user has been warned to save the token value immediately
  • The user can delete a token after confirmation
  • The agent has never displayed existing token values — only new tokens at creation time
</success_criteria>
<references>
  • 用户可以通过格式化表格查看所有个人访问令牌
  • 用户可以创建新令牌并获取令牌值
  • 用户已收到立即保存令牌值的提示
  • 用户可以在确认后删除令牌
  • Agent永远不会展示已存在的令牌值 — 仅在创建新令牌时展示一次
</success_criteria>
<references>

Composability

可组合性

  • AI Gateway: PATs are used to authenticate AI Gateway requests (
    ai-gateway
    skill)
  • GitOps / CI/CD: PATs are needed for automated deployments (
    gitops
    skill, 
    deploy
    skill declarative apply workflow)
  • Status: Use 
    status
    skill to verify a PAT is working
  • Secrets: Store PATs as secrets for deployments (
    secrets
    skill)
  • AI Gateway: PAT可用于认证AI Gateway请求（
    ai-gateway
    skill）
  • GitOps / CI/CD: PAT可用于自动化部署（
    gitops
    skill、
    deploy
    skill声明式应用工作流）
  • 状态检查: 使用
    status
    skill验证PAT是否可用
  • 密钥管理: 将PAT作为密钥存储用于部署（
    secrets
    skill）

API Endpoints

API端点

See 
references/api-endpoints.md
for the full Personal Access Tokens API reference.
</references> <troubleshooting>
完整的个人访问令牌API参考可查看
references/api-endpoints.md
。
</references> <troubleshooting>

Error Handling

错误处理

Permission Denied

权限被拒绝

Cannot manage access tokens. Check your API key permissions.
无法管理访问令牌，请检查你的API密钥权限。

Token Not Found

令牌未找到

Token ID not found. List tokens first to find the correct ID.
未找到对应Token ID，请先列出所有令牌确认正确的ID。

Token Name Already Exists

令牌名称已存在

A token with this name already exists. Use a different name.
该名称的令牌已存在，请使用其他名称。

Deleted Token Still In Use

已删除令牌仍在使用

If services fail after token deletion, they were using the deleted token.
Create a new token and update the affected services/pipelines.
如果删除令牌后服务出现故障，说明这些服务正在使用已删除的令牌。
请创建新令牌并更新受影响的服务/流水线。

Cannot Retrieve Token Value

无法获取令牌值

Token values are only shown at creation time. If lost, delete the old token
and create a new one, then update all services that used the old token.
</troubleshooting>
令牌值仅在创建时展示一次，如果丢失，请删除旧令牌
并创建新令牌，然后更新所有使用旧令牌的服务。
</troubleshooting>