How sign-in works
screenRIG issues short-lived signed access tokens and long-lived refresh tokens. The bundled CLI keeps both in its private config file and renews them on its own, so an agent never handles a token and never pastes one into a conversation.
| Credential | Lifetime |
|---|---|
| Access token | 10 minutes |
| Refresh token | Rotates on every use. It ends 90 days after its last use, and at most one year after sign-in. |
Sign-in code (screenrig login) | 24 hours |
| Service client token | 10 minutes, with no refresh token: the client asks for a new one |
There are four ways in:
| Who | How it signs in | Approved by |
|---|---|---|
| A new agent with no account | screenrig agent enroll creates the organization, the project and the session in one command, from an email address or an AgentID claim code | Enrollment itself; the person's emailed invitation follows |
| An agent for an existing account | screenrig login prints a code that a person approves in the dashboard | A project member, in the dashboard |
| A connected app (Claude, ChatGPT, Grok) | The app opens the screenRIG consent page; see remote server | A project member, on the consent page |
| A server, script or CI job | A service client signs in with its own key or secret | Created by a project member |
People sign in to the dashboard with a passkey or password, or through their organization's identity provider; see single sign-on and user provisioning.
Sign in with screenrig login
Use screenrig login when the person already has screenRIG and wants this agent installation to work in one of their projects. A new installation with no account starts with screenrig agent enroll instead; see Quickstart.
screenrig login- The CLI prints a dashboard address and an eight-letter code such as
BCDF-GHJK, then waits. - The person opens
https://screenrig.ai/dashboard/connect, signs in, and enters the code, or follows the full link that already carries it. - The dashboard shows the request on one screen: the installation name the device reported, when and where it asked, and the code. The person checks that the code matches the terminal, adjusts the project, the access level or the capabilities if they want, and presses Connect. A dashboard sign-in from the last hour is the proof, so Connect asks for nothing more; an older sign-in asks for a passkey. The dashboard then opens the new agent.
- The CLI stores the session, selects the approved project and reports
status: signed_inwith the project, organization and access level.
Approve only a sign-in you started yourself, on your own computer. The dashboard never approves anything on load, and an expired code needs a new screenrig login.
| Flag | Effect |
|---|---|
--access read, --access propose or --access manage | Ask for Read only, Propose or Manage. The default is manage; the person makes the final choice. |
--project prj_ID | Suggest the project the person approves. |
--name NAME | Name this installation, up to 80 characters. |
--no-wait | Return at once with the address, the code and a login_ handle. |
--resume login_ID | Wait for that pending sign-in to be approved and store its session. |
When the agent has to pass the address to a person in another channel first, use --no-wait. The handle holds no secret, and the pending sign-in stays in the private config file:
screenrig login --no-wait
screenrig login --resume login_HANDLEThe sign-in address and its code are for the person who approves it. Send them only to that person, and keep them out of logs and shared channels.
Add a project or raise access
An installation that is already signed in runs screenrig login again to add another project, or to raise a Read only or Propose project to Manage:
screenrig login --project prj_ID --access manageThe person approves that one change, and the installation keeps its other projects. screenrig project list shows every project the installation can use, and screenrig project use ID selects one.
Read only, Propose and Manage
Every session carries one of three access levels, chosen by the person who approves it. Each level includes everything the one before it can do.
| Read only | Propose | Manage | |
|---|---|---|---|
| List and read screens, playlists, media, events and playback | Yes | Yes | Yes |
| Upload and edit media, write project notes and comments, capture screenshots, send feedback and support messages, draft ad creatives and campaigns | No | Yes | Yes |
| Create and update playlists; assign, schedule or take over screens | No | Yes, as a review a person approves | Yes |
| Delete, pair, archive, reload, reboot, send toasts, set display power, tag screens, write application K/V, acknowledge, snooze or mute alerts, manage notifications and project settings | No | No | Yes |
| Buy ad slots and fund ad campaigns | No | No | Yes |
| Read the URL of a webhook receiver, fleet link or screen link | No: the URL reads as redacted | No: the URL reads as redacted | Yes |
| Counts toward the organization's hourly agent request cap | Yes | Yes | Yes |
Read only means the session cannot change or buy anything. Its requests count against the organization's hourly cap of agent requests, as they do for Propose and Manage.
Propose lets an agent do the work while a person keeps the final say over what plays. Its playlist and screen changes answer 202 with status: pending_review and a link to the review, and nothing changes on a screen until a person approves. Its media uploads, and its tag and folder changes to approved media, wait for review too: screens keep playing what was approved until a person approves the change, a rejection puts a changed item back, and a rejected upload stays off the screens. It cannot delete, control screens or spend.
A session that tries something its level cannot do gets 403 insufficient_access. The CLI names the next step: a person approves Manage with screenrig login --access manage.
Agent sign-ins default to Manage, and connected apps to Read only. To lower an installation, disconnect it, then sign in again with screenrig login --access read or --access propose. A session's level is never lowered silently: the review settings below hold sessions to Propose without changing them, and the Access page shows when they do.
Capabilities
Within its access level, a session works only in the capability areas the person approved: screens, content, playlists, advertising, reports and project. Enrollment grants all six on the project it creates. A command outside the approved areas returns 403 forbidden naming the missing capability. Capabilities stay as approved. For more, run screenrig login --project prj_ID again; the capabilities the person approves then replace the project's.
Require review for agent changes
Two settings hold agents to Propose without signing them in again. Both apply on every request, so they cover sessions that already exist.
- Require review for agent changes, on the dashboard's Settings page. While it is on, every agent, connected app and service client in the project works at Propose at most: changes to what plays wait in Reviews until a person approves them. The project owner or an admin of its organization changes it, and turning it off asks for their passkey. Reviews already waiting stay open to decide.
- Can approve, for each member on the project's Access page. The project owner always can approve. A member who cannot approve does not decide reviews and cannot give an agent Manage, and the agents that member is responsible for work at Propose at most.
The lowest level that applies wins. screenrig agent status reports the session's access, its effective_access and, when a setting lowers it, access_limited_by: project or person. Signing in again does not lift a setting; the project owner changes it. While a setting applies, the sign-in and connection approval screens offer Read only and Propose, and show why Manage is unavailable.
Uploaders
An uploader works in the playlists and media folders you choose and nowhere else. It uploads media into those folders and adds, replaces and removes pages of those playlists, with start and end dates. It cannot read or change other playlists, screens, schedules, members, tokens, fleet links, billing or settings. A person on an agency's team is an uploader member; an agency's agent is an uploader service client. Uploaders come with Plus and every plan above it; see Plus features.
- Invite or assign. On the dashboard's Access page, invite a person as an uploader or make a member an uploader, and pick the folders and playlists. From the CLI,
screenrig invitations create --kind uploader --email designer@example.com --folder-id mfd_FOLDER --playlist-id pl_PLAYLISTinvites one, andscreenrig service-client create --name "Agency agent" --uploader --folder-id mfd_FOLDER --playlist-id pl_PLAYLIST --secret-file agency.secretgives an agent its own token. The folders are exactly the ones you choose, not the folders inside them. The owner edits the scope or ends it at any time, and the change applies to the uploader's next request. - Propose, or publish without review. An uploader member's changes wait in Reviews until the project owner or a member who can approve decides them. The owner can let a member publish without review (
--access manage) when inviting or assigning. An uploader service client acts at the access it was created with, Propose unless you choose otherwise, and Require review for agent changes holds it to Propose as it holds every agent. An uploader never approves reviews and never connects agents: an agent gets an uploader token instead. - Upload and add pages.
screenrig media upload FILE --folder mfd_FOLDERuploads into a folder the uploader has.screenrig playlist page add pl_PLAYLIST --media med_IMAGE --from 2026-12-01 --until 2026-12-24adds the media as a page that is shown from the start of December 1 up to the end of December 24, in each screen's timezone;playlist page replaceswaps the media or changes the dates, andplaylist page removeremoves the page. A page the uploader adds is an image or video of its folders; the project's other pages stay as they are. Several uploads in a row by one uploader join one review, so the owner approves them together, and a page still waiting in it can be replaced or removed. Another uploader's change to the playlist waits until that review is decided. - In the dashboard. An uploader member signs in to a dashboard with one page, Upload, which lists its playlists and folders. In a folder it uploads files; on a playlist it adds a page from a picture or a clip, sets the first and last day the page shows, replaces or removes its own pages, and withdraws a change that waits for review. The project's other pages read Set by the project.
- Outside the scope. Everything else answers
outside_upload_scope, whoseupload_scopelists the playlists and folders the uploader may use.
To limit a member or an agent to screen folders and screens instead of content, see Permissions by screen folder.
The Access page
The dashboard's Access page lists everything that can act on the current project:
| Section | What it lists |
|---|---|
| Pending | Sign-ins and connection requests waiting for approval |
| People | Members and open invitations |
| Agents | CLI and plugin installations, enrolled or signed in |
| Connected apps | AI assistants a person connected, one entry per app |
| Service clients | Servers, scripts and CI jobs, with their keys and secrets |
Each entry shows how it got access and who approved it, its access level and capabilities, and when it was created and last used. When a review setting holds an entry below its level, the entry shows the level it works at and why, for example "Propose — project requires review". Disconnect ends an agent or app; Revoke ends a service client. Each asks the person to confirm with their passkey.
An organization holds up to 200 live agents across its projects. Past that, a sign-in is refused with agent_limit_exceeded until an agent is disconnected.
Sign out and revoke
| To end | Run or do |
|---|---|
| This installation's sign-in | screenrig logout |
| This installation's access to the current project | screenrig agent disconnect --yes |
| This installation everywhere | screenrig agent revoke-identity --yes |
| Any agent or connected app | Disconnect on the Access page |
| A service client | Revoke on the Access page, or screenrig service-client revoke ID --yes |
screenrig logout revokes the sign-in on the server, then removes the stored tokens. If the request might not have reached the server, the tokens stay, so running it again is safe. A Read only session can always disconnect itself. Disconnecting the project's last active agent also needs --allow-lockout.
A revoked session cannot renew: no new token is issued after the revoke. Its access tokens stop working within seconds. Deactivating the person responsible for an agent ends its sessions the same way, and deleting a project ends every session's access to that project.
Session length
Each use of the refresh token moves its end 90 days forward, up to one year after sign-in. screenrig doctor shows when this installation's session ends, and every command warns in its last 30 days. To continue, a person approves a new screenrig login.
Reference
These endpoints follow OAuth 2.0. The bundled CLI, connected apps and service clients use them; an agent working through the plugin never calls them directly.
| Item | Value |
|---|---|
| Issuer | https://api.screenrig.ai |
| Authorization server metadata | https://api.screenrig.ai/.well-known/oauth-authorization-server |
| Protected resource metadata | https://api.screenrig.ai/.well-known/oauth-protected-resource/api |
| Token endpoint | https://api.screenrig.ai/oauth/token |
| Device authorization | https://api.screenrig.ai/oauth/device_authorization |
| Authorization endpoint | https://api.screenrig.ai/oauth/authorize |
| Revocation | https://api.screenrig.ai/oauth/revoke |
| Grant types | authorization_code (PKCE S256 only), refresh_token, urn:ietf:params:oauth:grant-type:device_code, client_credentials |
| Client authentication | none, private_key_jwt (EdDSA, ES256, RS256), client_secret_basic |
| Scopes | access:read, access:propose, access:manage, identity, and the capabilities screens, content, playlists, advertising, reports, project |
| Resources | https://api.screenrig.ai/api (the default) and https://api.screenrig.ai/mcp |
Access tokens are JWTs signed with Ed25519 (EdDSA): an EdDSA-only profile using the claim conventions of RFC 9068 (typ: at+jwt, iss, aud, sub, client_id, scope, jti, iat, exp). Treat them as opaque: send each one as Authorization: Bearer and request a new one when it expires.
Token endpoint errors are RFC 6749 JSON (error, error_description) with Cache-Control: no-store:
error | Meaning | CLI problem |
|---|---|---|
invalid_grant | The session was revoked, expired or reused, or a code is wrong | session_ended: run screenrig login |
invalid_client | Unknown client, or a wrong key, secret or assertion | client_auth_failed |
invalid_scope | More access or capabilities than were approved | insufficient_access |
invalid_target | A resource other than the two above | invalid_request |
authorization_pending, slow_down | A sign-in still waiting for approval | The CLI keeps waiting |
access_denied | The person denied the sign-in | login_denied |
expired_token | The sign-in code expired | login_expired: run screenrig login |
temporarily_unavailable | Try again shortly | service_unavailable |
rate_limited | Wait for Retry-After | rate_limited |
Requests to /api with an expired or revoked access token answer 401 with WWW-Authenticate: Bearer error="invalid_token"; the CLI renews once and retries once. A token calling something its access level cannot do answers 403 insufficient_access with WWW-Authenticate: Bearer error="insufficient_scope" and the scope that allows it. A credential from an old plugin or CLI answers 401 credential_retired; update the official plugin and run screenrig login.
The token and revocation endpoints accept 1,200 requests per client address per hour, 60 renewals per session per hour and 600 service-client tokens per client per hour. Sign-in starts are limited to 10 per address per hour.