登录工作原理
screenRIG 颁发短期签名访问令牌和长期刷新令牌。捆绑的 CLI 将两者保存在私有配置文件中并自动续期，因此智能体无需处理令牌，也无需将令牌粘贴到对话中。
| 凭据 | 生命周期 |
|---|---|
| 访问令牌 | 15 分钟 |
| 刷新令牌 | 每次使用时轮换。最后一次使用后 90 天结束，且最多在登录后一年结束。 |
登录代码（screenrig login） | 24 小时 |
| 服务客户端令牌 | 15 分钟，无刷新令牌：客户端请求新的令牌 |
有四种进入方式：
使用screenrig login登录
当用户已有 screenRIG 并希望此智能体安装在其某项目中使用时，使用 screenrig login。无账户的新安装则从 screenrig agent enroll 开始；参见 开始。
screenrig login- CLI 打印一个仪表盘地址和一个八字母代码，如
BCDF-GHJK，然后等待。 - 该人员打开
https://screenrig.ai/dashboard/connect，登录并输入代码，或访问已携带代码的完整链接。 - 控制台在一屏上显示请求：设备报告的安装名称、请求时间和地点及代码。人员检查代码是否与终端匹配，调整项目、访问级别或权限（如需要），然后按连接。最近一小时内的控制台登录即为凭证，因此连接不再要求其他内容；较早的登录要求通行密钥。控制台随后打开新智能体。
- CLI 存储会话，选择批准的项目，并报告
status: signed_in，包含项目、组织和访问级别。
仅批准自己在本机启动的登录。仪表板加载时从不自动批准，过期代码需新的 screenrig login。
| 标记 | 效果 |
|---|---|
--access read，--access propose 或 --access manage | 请求只读、提议或管理。默认是 manage；由人员最终选择。 |
--project prj_ID | 建议用户批准的项目。 |
--name NAME | 为此安装命名，最多 80 个字符。 |
--no-wait | 立即返回，包含地址、代码和一个 login_ 句柄。 |
--resume login_ID | 等待待处理的登录被批准并存储其会话。 |
当智能体必须先将地址传递给另一个频道中的人员时，使用 --no-wait。该句柄不包含任何秘密，待处理的登录信息保存在私有配置文件中：
screenrig login --no-wait
screenrig login --resume login_HANDLE登录地址及其代码仅供批准者使用。仅发送给该人，避免出现在日志和共享渠道。
添加项目或提升访问权限
已登录的安装再次运行screenrig login以添加另一个项目，或将只读或提议项目提升为管理权限：
screenrig login --project prj_ID --access manage该人员批准了该更改，安装保留其其他项目。screenrig project list显示安装可用的所有项目，screenrig project use ID选择其中一个。
只读、提议和管理
每个会话都有三种访问级别之一，由批准者选择。每个级别包含前一个级别的所有权限。
| 只读 | 提议 | 管理 | |
|---|---|---|---|
| 列出并读取屏幕、播放列表、媒体、事件和播放 | 是 | 是 | 是 |
| 上传和编辑媒体，编写项目备注，捕获截图，发送反馈和支持消息，草拟广告创意和广告活动 | 否 | 是 | 是 |
| 创建和更新播放列表；分配、排程或接管屏幕 | 否 | 是，作为 审核 由人员批准 | 是 |
| 删除、配对、归档、重新加载、重启、发送提示、设置显示器电源、标记屏幕、写入应用 K/V、确认、暂缓或静音警报、管理通知和项目设置 | 否 | 否 | 是 |
| 在购买、广告活动或图像生成上花费额度 | 否 | 否 | 是 |
| 读取 webhook 接收器 URL | 无：URL 显示为已编辑 | 无：URL 显示为已编辑 | 是 |
| 按请求计费，如每个智能体请求一样 | 是 | 是 | 是 |
只读意味着会话不能更改或购买任何内容。它不意味着免费：每个代理请求和计费的监听流事件都计入组织的 包含请求，Propose 和 Manage 亦然。
提议允许智能体执行工作，而人保留对播放内容的最终决定权。其播放列表和屏幕更改通过 202 回应 status: pending_review 并附带审核链接，屏幕上的内容在人员批准前不变。其媒体上传及标签和文件夹更改为已批准媒体，也需等待审核：屏幕继续播放已批准内容，直到人员批准更改，拒绝则恢复更改项，拒绝的上传不会显示在屏幕上。它不能删除、控制屏幕或花费。
尝试执行其权限不足操作的会话获得 403 insufficient_access。CLI 指明下一步：人员使用 screenrig login --access manage 批准 Manage。
智能体登录默认权限为管理，连接的应用为只读。要降低安装权限，请断开连接，然后使用 screenrig login --access read 或 --access propose 重新登录。会话权限不会静默降低：下面的审核设置将会话保持为提议状态而不更改，访问页面显示权限变更情况。
功能
在其访问级别内，会话仅在人员批准的能力区域内工作：screens、content、playlists、advertising、reports 和 project。注册时会在其创建的项目上授予全部六项能力。超出批准区域的命令返回 403 forbidden，指出缺失的能力。能力在安装的项目中保持批准状态；如需更多，人员需批准拥有这些能力的新安装。
要求智能体更改需审核
两个设置使代理保持提议访问权限，无需重新登录。两者在每次请求时生效，覆盖已有会话。
- 智能体更改需审核，在控制台的 设置 页面。启用时，项目中的所有智能体、连接的应用和服务客户端最多以提议身份工作：播放内容的更改会在 审核 中等待人员批准。项目所有者或其组织的管理员可更改此设置，关闭时需其通行密钥。已等待的审核保持开放以供决定。
- 可审批，针对项目“访问权限”页面的每个成员。项目所有者始终可审批。不可审批成员不决定审核，且无法赋予智能体管理权限，该成员负责的智能体最多在提议阶段工作。
适用的最低级别生效。screenrig agent status 报告会话的 access、其 effective_access，以及当设置降低时的 access_limited_by：project 或 person。重新登录不会提升设置；项目所有者可更改。设置生效时，登录和连接批准屏幕提供只读和提议选项，并显示管理不可用的原因。
上传者
上传者只能在您选择的播放列表和媒体文件夹中工作，其他地方一概不能。它可以向这些文件夹上传媒体，并为这些播放列表添加、替换和移除页面，且可设置开始和结束日期。它不能读取或更改其他播放列表、屏幕、计划、成员、令牌、车队链接、账单或设置。代理机构团队中的人是上传者成员；代理机构的智能体是上传者服务客户端。
- 邀请或分配。在控制台的访问页面，邀请某人成为上传者，或将成员设为上传者，并选择文件夹和播放列表。通过 CLI，
screenrig invitations create --kind uploader --email designer@example.com --folder-id mfd_FOLDER --playlist-id pl_PLAYLIST可邀请一名上传者，screenrig service-client create --name "Agency agent" --uploader --folder-id mfd_FOLDER --playlist-id pl_PLAYLIST --secret-file agency.secret可为智能体提供专属令牌。文件夹仅限您所选的那些，不包括其中的子文件夹。所有者可随时编辑范围或终止它，更改将在上传者的下一次请求时生效。 - 提议，或不经审核直接发布。上传者成员的更改会在审核中等待，直到项目所有者或有权批准的成员作出决定。所有者可在邀请或分配时允许成员不经审核发布（
--access manage）。上传者服务客户端使用其创建时的访问级别，除非另行选择，否则为提议；“要求智能体更改需审核”会像对待所有智能体一样将其保持在提议级别。上传者从不批准审核，也从不连接智能体：智能体改用上传者令牌。 - 上传并添加页面。
screenrig media upload FILE --folder mfd_FOLDER会上传到该上传者拥有的文件夹。screenrig playlist page add pl_PLAYLIST --media med_IMAGE --from 2026-12-01 --until 2026-12-24会将媒体添加为一个页面，按各屏幕的时区，从 12 月 1 日开始显示，到 12 月 24 日结束；playlist page replace会替换媒体或更改日期，playlist page remove会移除该页面。上传者添加的页面是其文件夹中的图片或视频；项目的其他页面保持不变。同一上传者连续的多次上传会归入同一个审核，因此所有者可以一并批准，其中仍在等待的页面也可以替换或移除。另一位上传者对播放列表的更改会等到该审核有结果后再处理。 - 在控制台中。上传者成员登录后看到的控制台只有一个页面“上传”，其中列出其播放列表和文件夹。在文件夹中，上传者上传文件；在播放列表中，上传者可用图片或视频片段添加页面，设置页面显示的第一天和最后一天，替换或移除自己的页面，并撤回等待审核的更改。项目的其他页面显示为“由项目设置”。
- 超出范围。其他所有请求都会返回
outside_upload_scope，其upload_scope列出该上传者可以使用的播放列表和文件夹。
若要把成员或智能体限定在屏幕文件夹和屏幕而不是内容，请参见按屏幕文件夹设置权限。
访问页面
控制台的 访问 页面列出所有可对当前项目操作的内容：
| 部分 | 它列出了什么 |
|---|---|
| 待处理 | 等待批准的登录和连接请求 |
| 人员 | 成员和开放邀请 |
| 智能体 | CLI 和插件安装，已注册或已登录 |
| 已连接的应用 | 人工智能助手，已连接人员，每个应用一条记录。 |
| 服务客户端 | 服务器、脚本和 CI 任务及其密钥和密钥秘密 |
每条记录显示其访问方式、批准人、访问级别和权限，以及创建和最近使用的时间。当审核设置将记录限制在某级别以下时，记录会显示其实际工作级别及原因，例如“建议 — 项目需审核”。断开连接用于结束智能体或应用；撤销用于结束服务客户端。每项操作都要求成员用通行密钥确认。
退出并撤销
| 结束 | 运行或执行 |
|---|---|
| 此安装的登录状态 | screenrig logout |
| 此安装对当前项目的访问权限 | screenrig agent disconnect --yes |
| 此处安装 | screenrig agent revoke-identity --yes |
| 任何智能体或连接的应用 | 访问页面上的断开连接 |
| 服务客户端 | 撤销，在访问页面，或 screenrig service-client revoke ID --yes |
screenrig logout 撤销服务器上的登录，然后移除存储的令牌。如果请求可能未到达服务器，令牌保留，因此再次运行安全。只读会话始终可以自行断开连接。
被撤销的会话无法续期：撤销后不再发放新令牌。其访问令牌在几秒内失效。停用智能体负责人同样结束其会话，删除项目则结束所有会话对该项目的访问。
会话时长
每次使用刷新令牌都会将其结束时间向后延长 90 天，最长可达登录后一年。screenrig doctor 显示本次安装的会话结束时间，每条命令在最后 30 天内都会发出警告。要继续，需要成员批准新的 screenrig login。
现有凭据
之前登录过的安装会继续工作。在下一条命令中，捆绑的 CLI 会交换存储的凭证以获得具有相同项目和功能的会话，无需提示且无输出。更新官方插件以获取该 CLI；智能体无其他变化。
参考
这些端点遵循 OAuth 2.0。捆绑的 CLI、连接的应用和服务客户端使用它们；通过插件工作的智能体从不直接调用它们。
| 项目 | 值 |
|---|---|
| 发行者 | https://api.screenrig.ai |
| 授权服务器元数据 | https://api.screenrig.ai/.well-known/oauth-authorization-server |
| 受保护资源元数据 | https://api.screenrig.ai/.well-known/oauth-protected-resource/api |
| 令牌端点 | https://api.screenrig.ai/oauth/token |
| 设备授权 | https://api.screenrig.ai/oauth/device_authorization |
| 授权端点 | https://api.screenrig.ai/oauth/authorize |
| 撤销 | https://api.screenrig.ai/oauth/revoke |
| 授权类型 | authorization_code（仅限 PKCE S256），refresh_token，urn:ietf:params:oauth:grant-type:device_code，client_credentials，urn:ietf:params:oauth:grant-type:token-exchange |
| 客户端认证 | none, private_key_jwt (EdDSA, ES256, RS256), client_secret_basic |
| 范围 | access:read，access:propose，access:manage，identity，以及功能 screens，content，playlists，advertising，reports，project |
| 资源 | https://api.screenrig.ai/api（默认）和 https://api.screenrig.ai/mcp |
访问令牌是使用 Ed25519 (EdDSA) 签名的 JWT：一个仅 EdDSA 的配置文件，使用 RFC 9068 (typ: at+jwt、iss、aud、sub、client_id、scope、jti、iat、exp) 的声明约定。将其视为不透明：每个令牌作为 Authorization: Bearer 发送，过期时请求新的。
令牌端点错误为 RFC 6749 JSON（error、error_description），带有 Cache-Control: no-store：
error | 含义 | CLI 问题 |
|---|---|---|
invalid_grant | 会话被撤销、过期或重用，或代码错误。 | session_ended：运行screenrig login |
invalid_client | 未知客户端，或密钥、密钥秘密或断言错误 | client_auth_failed |
invalid_scope | 访问权限或功能超过批准范围 | insufficient_access |
invalid_target | 除上述两者之外的 resource | invalid_request |
authorization_pending, slow_down | 仍在等待批准的登录 | CLI 持续等待中 |
access_denied | 该人员拒绝登录 | login_denied |
expired_token | 登录代码已过期。 | login_expired：运行screenrig login |
temporarily_unavailable | 请稍后再试 | service_unavailable |
rate_limited | 等待 Retry-After | rate_limited |
使用过期或吊销访问令牌请求 /api 时，返回 401 和 WWW-Authenticate: Bearer error="invalid_token"；CLI 重新一次并重试一次。令牌调用其访问级别无法执行的操作时，返回 403 insufficient_access 和 WWW-Authenticate: Bearer error="insufficient_scope" 以及允许该操作的 scope。
令牌和撤销端点每客户端地址每小时接受 1,200 次请求，每会话每小时允许 60 次续期，每客户端每小时允许 600 个服务客户端令牌。登录启动限制为每地址每小时 10 次。