Documentation

Sign agents in with access you control

Every agent, app and script that works on your screens signs in with its own session. A person approves each one in the dashboard, chooses Read only, Propose or Manage, and can end it from the Access page at any time.

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.

CredentialLifetime
Access token10 minutes
Refresh tokenRotates 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 token10 minutes, with no refresh token: the client asks for a new one

There are four ways in:

WhoHow it signs inApproved by
A new agent with no accountscreenrig agent enroll creates the organization, the project and the session in one command, from an email address or an AgentID claim codeEnrollment itself; the person's emailed invitation follows
An agent for an existing accountscreenrig login prints a code that a person approves in the dashboardA project member, in the dashboard
A connected app (Claude, ChatGPT, Grok)The app opens the screenRIG consent page; see remote serverA project member, on the consent page
A server, script or CI jobA service client signs in with its own key or secretCreated 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
  1. The CLI prints a dashboard address and an eight-letter code such as BCDF-GHJK, then waits.
  2. The person opens https://screenrig.ai/dashboard/connect, signs in, and enters the code, or follows the full link that already carries it.
  3. 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.
  4. The CLI stores the session, selects the approved project and reports status: signed_in with 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.

FlagEffect
--access read, --access propose or --access manageAsk for Read only, Propose or Manage. The default is manage; the person makes the final choice.
--project prj_IDSuggest the project the person approves.
--name NAMEName this installation, up to 80 characters.
--no-waitReturn at once with the address, the code and a login_ handle.
--resume login_IDWait 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_HANDLE

The 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 manage

The 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 onlyProposeManage
List and read screens, playlists, media, events and playbackYesYesYes
Upload and edit media, write project notes and comments, capture screenshots, send feedback and support messages, draft ad creatives and campaignsNoYesYes
Create and update playlists; assign, schedule or take over screensNoYes, as a review a person approvesYes
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 settingsNoNoYes
Buy ad slots and fund ad campaignsNoNoYes
Read the URL of a webhook receiver, fleet link or screen linkNo: the URL reads as redactedNo: the URL reads as redactedYes
Counts toward the organization's hourly agent request capYesYesYes

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_PLAYLIST invites one, and screenrig service-client create --name "Agency agent" --uploader --folder-id mfd_FOLDER --playlist-id pl_PLAYLIST --secret-file agency.secret gives 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_FOLDER uploads into a folder the uploader has. screenrig playlist page add pl_PLAYLIST --media med_IMAGE --from 2026-12-01 --until 2026-12-24 adds 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 replace swaps the media or changes the dates, and playlist page remove removes 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, whose upload_scope lists 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:

SectionWhat it lists
PendingSign-ins and connection requests waiting for approval
PeopleMembers and open invitations
AgentsCLI and plugin installations, enrolled or signed in
Connected appsAI assistants a person connected, one entry per app
Service clientsServers, 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 endRun or do
This installation's sign-inscreenrig logout
This installation's access to the current projectscreenrig agent disconnect --yes
This installation everywherescreenrig agent revoke-identity --yes
Any agent or connected appDisconnect on the Access page
A service clientRevoke 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.

ItemValue
Issuerhttps://api.screenrig.ai
Authorization server metadatahttps://api.screenrig.ai/.well-known/oauth-authorization-server
Protected resource metadatahttps://api.screenrig.ai/.well-known/oauth-protected-resource/api
Token endpointhttps://api.screenrig.ai/oauth/token
Device authorizationhttps://api.screenrig.ai/oauth/device_authorization
Authorization endpointhttps://api.screenrig.ai/oauth/authorize
Revocationhttps://api.screenrig.ai/oauth/revoke
Grant typesauthorization_code (PKCE S256 only), refresh_token, urn:ietf:params:oauth:grant-type:device_code, client_credentials
Client authenticationnone, private_key_jwt (EdDSA, ES256, RS256), client_secret_basic
Scopesaccess:read, access:propose, access:manage, identity, and the capabilities screens, content, playlists, advertising, reports, project
Resourceshttps://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:

errorMeaningCLI problem
invalid_grantThe session was revoked, expired or reused, or a code is wrongsession_ended: run screenrig login
invalid_clientUnknown client, or a wrong key, secret or assertionclient_auth_failed
invalid_scopeMore access or capabilities than were approvedinsufficient_access
invalid_targetA resource other than the two aboveinvalid_request
authorization_pending, slow_downA sign-in still waiting for approvalThe CLI keeps waiting
access_deniedThe person denied the sign-inlogin_denied
expired_tokenThe sign-in code expiredlogin_expired: run screenrig login
temporarily_unavailableTry again shortlyservice_unavailable
rate_limitedWait for Retry-Afterrate_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.