Permissions by screen folder

Who is limited

• A member. The project owner limits a member to chosen screen folders and screens. The member signs in as before and sees and changes only their own screens.
• An agent. The owner limits an agent the same way. An agent also never reaches further than the person responsible for it: its reach is its own scope narrowed by that person's, so a limited person never acts through a wider agent.
• Never limited. The project owner and service clients of the whole project.

A limit is a scope. It is read on every request, never stored in a token or a session, so a change applies to the person's next request without signing in again. A caller with no scope works on the whole project and pays nothing for the check.

Folders and inheritance

Screen folders are the hierarchy. A scope that names a folder holds every screen in that folder and in every folder inside it, and it follows the folder when the folder moves.

Hotel
  Lobby            <- the lobby manager's scope holds Lobby and Bar
    Bar
  Casino Floor     <- the floor manager's scope holds Casino Floor
  Rooms

• A scope holds up to 1,000 folders and 200 single screens, and at least one of the two.
• A single screen can sit in any number of scopes, and so can a folder.
• Ids must name live folders and screens of the project when the scope is written. A folder or screen deleted later leaves an id that grants nothing.
• A member who approves reviews is limited to folders. Single screens are for members who do not approve.
• A person is either limited to screens or an uploader, never both: an uploader is limited to content, a limited member to screens.

Set a scope

Only the project owner sets, changes or ends a scope, in the dashboard.

1. Open the dashboard's Access page.
2. Under People, open the member and use Screens. Check the folders, which include everything inside them, and add single screens if the member does not approve. Save.
3. For an agent, open it under Agents and use the same Screens control.
4. To limit a person before they join, add the scope to the invitation.

Remove the scope in the same place to give the member the whole project again.

Setting a member's scope ends the agents that person brought to the project, so nothing keeps the wider reach it was given before. A scope is refused while the person, or an agent they brought, holds a live service client of the project: revoke each client the refusal names and set the scope again. Transferring the project to a member removes that member's scope.

A member invited with a scope joins as a member who cannot approve. The owner turns on Can approve for them on the same page when they should decide reviews for their folders.

What a limited person does and sees

Inside the scope a limited person works as a member of the project does, in the dashboard, with the CLI and over the API:

• Screens. Read, health, plays, uptime, screenshots and live view, comments, commands such as reboot, clear cache, identify and update, tags, fields, location, name, playlist, playlist schedule, takeover, archive and delete.
• Folders. Create, rename, move and delete folders inside the scope, and set a folder's default playlist. The folder a scope names stays: only a person with a wider scope deletes it.
• Moves. A screen or folder moves from one place inside the scope to another. The source and the destination are both inside it.
• Campaigns. Create, change and delete a campaign whose whole audience is inside the scope.
• Fleet actions. Select screens by id or by folder inside the scope.
• New screens. A limited person who can approve pairs or provisions a screen into a folder of the scope. The new screen names its folder, so it lands inside the scope.
• Notes. Read and write the notes about their own screens, about playlists and about nothing.

Content (media, playlists, applications, cards, card data) stays governed by the member's role, exactly as for any member.

A limited person reaches no project administration: members, invitations, service clients, agent sign-ins, fleet links, billing, settings, webhooks, notifications, alerts, triggers, schedule imports and project-wide reports are refused. Each answers outside_screen_scope.

A campaign is editable only inside the scope

A campaign is listed to everyone, and a limited person edits it only when its whole audience is inside their scope. Otherwise editable is false and the campaign is read-only to them.

• A folder or screen in the scope is inside it.
• An any rule is inside when every child is.
• An all rule is inside when at least one child is, because it is an intersection.
• A tag rule, and the rule for every screen, are never inside.

A limited person who cannot approve

A limited member who cannot approve reviews reads everything in the scope and runs commands, screenshots and comments, and changes what plays only through an approver. Assigning a playlist, schedules, takeovers, campaigns, folders and moves answer approver_required for them. A member without a scope is unchanged.

What is outside the scope

Screens outside the scope are hidden from every list: the screens list, a folder's screens, campaign screens, the calendar, events and the live stream. The folder tree shows the scope's folders and the folders above them, read-only and without a screen count, so the tree has a root. Their siblings are hidden.

A request that names a screen, folder, selector or audience outside the scope is refused whole and never narrowed: nothing is written. An id outside the scope and an id that does not exist get the same answer.

{
  "status": 403,
  "errors": [
    {
      "code": "outside_screen_scope",
      "screen_scope": { "folder_ids": ["sfd_01LOBBY"], "screen_ids": [] },
      "hint": "Ask the project owner to widen the scope, or leave this to a member of the whole project."
    }
  ]
}

screen_scope names the caller's own scope, so the caller can tell what it may use. Playback records, the calendar and the Player log take a screen of the scope (the calendar also a folder). Project-wide health trend and daily uptime are refused; the per-screen health history and uptime are open.

Delegated administration

Give a venue manager their folders and let them run them:

1. The owner limits the manager to the venue's folders.
2. The owner turns on Can approve for the manager.
3. The manager assigns playlists, schedules and campaigns in their folders directly, and decides the reviews that agents propose for those folders.

An approver who is limited decides only a review whose whole reach is inside their scope, and the Reviews page lists only those. A limited approver decides no ad creative review. A review that reaches a screen outside the scope answers outside_screen_scope.

Protected folders

A protected folder is for screens where no single person changes what plays. A person who can approve turns on Protected for a folder in the dashboard, and the protection covers every folder inside it. Agents and service clients never protect a folder, and an agent removes protection only as a proposal: screenrig screen folder update ID --unprotect becomes a review that a second approver decides. A limited approver protects folders inside their scope, not a folder their scope names. A change that reaches a screen in a protected folder becomes a review that a second approver decides, at every access level, Manage included.

An agent that assigns a playlist to a screen in a protected folder gets pending_review and the review. The screen keeps playing what it played until a second approver decides.

screenrig screen assign scr_01EXAMPLESCREEN000000000 --playlist-id pl_01WELCOME
screenrig reviews list --kind protected_change
screenrig reviews show rvw_01EXAMPLEREVIEW0000000000

What happens to a change depends on the change:

• A review. Assigning a playlist, setting or clearing a playlist schedule or a takeover, on one screen or a fleet, is a screen_change review. Creating, changing or deleting a campaign whose audience reaches a protected screen, creating a folder inside a protected folder, moving, deleting or setting the default playlist of a folder in or holding one, moving screens or folders into or out of one, and clearing protection are a protected_change review. The change is applied in the approving decision. A rename is live.
• A refusal. Tag, field, location, timezone and wall edits, replacing a screen, deleting, archiving, suspending, display power and its schedule, a play page, a toast, ad inventory, trigger targets and schedule imports that reach a protected screen answer protected_target. To make the change, an approver clears protection through a review, the change is made, and the folder is protected again. A trigger that fans out leaves protected screens as they are and counts them.
• Open. Resuming, unarchiving, rebooting, reloading, identifying, maintenance and screenshots stay open.

A review waits for a person other than the proposer and other than the person responsible for the proposing agent or service client. The decision is refused with second_approver_required when the decider is the same person. When the project has only one approver, the refusal says to make another member an approver. A change proposed before its folder was protected meets the rule when it is approved. A review that has gone out of date while it waited answers review_stale; propose the change again.

A project with no protected folder pays nothing for the rule.

Reserved campaigns

A campaign marked Reserved is changed, paused, deleted or un-reserved only by a person who can approve reviews: the owner, or an approver whose scope holds the campaign's whole audience. A person turns on Reserved in the campaign's form in the dashboard. Agents and service clients never change a reserved campaign, at any access level, and their attempts answer reserved_item. Reserve the campaign that carries a brand's fixed schedule, and a manager or an agent cannot change it by accident.

Tags are not scope

A scope is folders and single screens. Anyone who may change a screen can write its tags, so a tag scope would let one manager extend their own reach or another manager's. Use folders for ownership and tags for selection inside it.

A fleet action or campaign that selects by tag is refused to a limited person whole, with outside_screen_scope, and the hint says to select by ids or by folder.

Agents

A limited agent works with the CLI the way a limited member does in the dashboard.

screenrig agent status
screenrig screen list
screenrig screen folder list
screenrig screen pair "$PAIRING_CODE" --folder sfd_01LOBBY --name "Lobby entrance"
screenrig screen assign scr_01EXAMPLESCREEN000000000 --playlist-id pl_01WELCOME
screenrig screen folder update sfd_01LOBBY --unprotect
screenrig campaign show cmp_01EXAMPLECAMPAIGN0000000

• agent status shows the agent's screen_scope and the person_screen_scope of the person responsible for it.
• screen list and screen folder list hold only its screens and folders.
• screen pair takes --folder and needs a folder of the scope.
• screen folder update ID --unprotect proposes removing a folder's protection, sent alone. It becomes a review that a second approver decides.
• campaign show prints editable and reserved.
• With no project selected, screen list leaves out a project where the agent is limited. Select the project.

Refusals and how to fix them

Every refusal names the way back in its hint.

A protected change that is accepted answers 202 with status: pending_review and the review, the same answer a Propose agent gets. Follow it with screenrig reviews show ID.

Audit

Every change is an event in the project's log, written in the transaction that makes the change:

Reviews write the usual review.* events, and the approving person is the actor of what a review applies.

API

The owner's routes take the dashboard session.

The API reference lists every request, answer and problem. The problems are in the problem types.

Related

• Authentication: access levels, review settings and uploaders.
• Agents: how reviews work for an agent's changes.
• Signage CLI: screen folders and fleet commands.
• Service clients: credentials for servers and CI jobs.