个人访问令牌适合 CI、定时任务、内部服务或其他自动化客户端。它不是给浏览器免登录使用的“永久 Cookie”，也不会默认继承你的全部保险库权限。第一次接入时，按下面的顺序操作最清楚。

1. 为一个具体使用方创建令牌

解锁 xypass，进入“设置 → 访问令牌”。使用“服务 + 环境 + 用途”命名，例如“GitLab CI / Production / Deploy”，不要只写“测试”或“Token”。一个应用或服务使用一个令牌，方便以后单独查看和撤销。

选择尽可能短、但能覆盖实际维护周期的有效期。创建、续期、授权和撤销属于高风险操作，页面可能要求你重新输入账户密码或通过 OIDC 再次确认身份。

2. 立即保存一次性凭据包

创建成功后，页面会显示一份 JSON 凭据包，其中包含服务器地址、auth_token、客户端使用的 capability_key 和令牌元数据。它只显示一次；关闭卡片、离开页面或锁定保险库后，不能从令牌列表重新取回完整内容。

把凭据下载到该服务专用的 Secret Store、操作系统凭据库或权限为 0600 的受控文件。不要提交到 Git、写进镜像、放入普通环境配置模板，也不要粘贴到工单和聊天记录。

3. 再授予明确目标

新令牌默认没有任何数据权限。选择刚创建的令牌，再选择目标类型：整个 Vault，或某个 Vault 中的一条 Item。然后从 viewer、editor、manager 中选择角色。

不确定时从单条 Item 的 viewer 开始。只有任务需要写回时才使用 editor；只有自动化确实要管理目标成员或邀请时才考虑 manager。更多判断见访问令牌的三种角色应该怎么选。

4. 在客户端建立机器会话

把凭据包交给兼容 xypass PAT 协议的客户端。客户端会为当前安装生成独立设备密钥，用长期 PAT 凭据换取最长两小时的机器会话，再在本地解开获授权目标。原始 PAT 不是直接调用所有业务接口的永久 Bearer。

当前 Web App 已提供令牌创建和权限管理，统一 PAT API 也已发布；不要假设设计文档中的通用 xypass CLI 命令已经作为独立成品分发。

5. 用最小动作验收

先执行一次只读操作，确认客户端只能看到预期 Vault 或 Item。若使用 editor，再写入一条可删除的测试变更，并回到 Web App 检查结果。最后查看令牌列表中的“最后使用”和授权数。

如果客户端看不到数据，先检查令牌是否过期、是否已经授予目标、目标和角色是否正确，而不是继续扩大权限。完成后把令牌名称、负责人、到期时间和用途记入你的服务清单。