Roles: user, auditor, admin

Every checkout has a role. Pick the one that matches what you’re granting: user (access) · auditor (scoped oversight) · admin (control plane). For the full field list see the Payload reference.

user

A standard access grant. A user can connect to their target, end their own sessions, and issue a view-only share link for their own live session. Users cannot create checkouts, see anyone else’s sessions, or control sessions.

In the web interface: the user signs in and lands on the picker (/picker), which lists their active checkouts. From a row they copy the native connection details (address / username / ready-to-run command) or click Connect to open a recorded browser session in a new tab. Expanding a row shows its active sessions, where the owner can Share (mint a view-only watch link) or End the session.

For a user checkout, configure the SSH permission example. It installs a generated key on an existing account and registers the checkout through bsh:

checkout.sh

#!/bin/sh
exec bsh checkout ssh --method existing-user-key --mode bridge

checkin.sh

#!/bin/sh
exec bsh checkin ssh --method existing-user-key --mode bridge

See Examples by protocol for other permission methods.

auditor

An oversight grant scoped by an audit_scope object. An auditor reviews recordings and (within scope) watches live sessions and performs control actions - but never connects to a backend. An auditor checkout requires an audit_scope. The auditor signs in through Bridge web authentication.

audit_scope fields:

Field	Type	Description
`users`	array	Only these checkout usernames are in scope. `*` = any.
`protocols`	array	Only these protocols.
`targets`	array	Only these target hosts (`host[:port]`; supports `` and `.suffix`).
`target_usernames`	array	Only these backend usernames.
`transaction_ids`	array	Only these specific checkouts.
`session_ids`	array	Only these specific sessions.
`artifacts`	array	What may be downloaded: `recording`, `har`, `queries` (or `*`).
`allow_live_view`	boolean	Allow watching in-scope sessions live.
`controls`	array	Live-session actions allowed: `lock`, `unlock`, `disconnect` (or `*`). Granting any control implies live-view.

An empty scope list means “match nothing” for that dimension, not “match everything.” To scope to all users, set "users": ["*"] - don’t leave it out.

Configure the common bsh settings and these scope variables for the auditor permission:

BSH_AUDIT_USERS=*
BSH_AUDIT_PROTOCOLS=ssh,rdp
BSH_AUDIT_TARGETS=*.prod.example.com,10.0.0.0:22
BSH_AUDIT_TARGET_USERNAMES=root,Administrator
BSH_AUDIT_ARTIFACTS=recording,har,queries
BSH_AUDIT_LIVE_VIEW=true
BSH_AUDIT_CONTROLS=lock,unlock,disconnect

bsh sends * for each scope list you leave unset. Each specified list narrows its own dimension. This differs from raw API payloads, where an empty list matches nothing. Review all scope values before enabling the permission.

checkout.sh

#!/bin/sh
exec bsh checkout bridge --method auditor-session

checkin.sh

#!/bin/sh
exec bsh checkin bridge --method auditor-session

The method selects Bridge mode automatically. It changes no target account. Checkin removes the auditor checkout.

In the web interface: an auditor signs in and reviews sessions from the session list - replaying recordings for anything in scope and, when allow_live_view is set, opening an in-scope live session to watch. If their scope grants controls, the live viewer exposes Lock / Unlock (freeze the user’s input while the screen stays visible) and Disconnect user. Anything outside their audit_scope is not shown to them. See Live Sessions & Sharing for the oversight view.

admin

The control plane. A temporary administrator can revoke checkouts, view and live-watch every session, lock/unlock/force-disconnect sessions, issue and revoke share links for any session, and install or remove licenses.

Web login authenticates identity. An admin checkout grants administration for a bounded window, but cannot directly create further checkouts. Creation requires private broker authority, an enabled external checkout token, or an independently authorized permanent administrator.

When checkout API tokens are enabled in v3.0.2, active admins can create checkout tokens in Admin > API Tokens. Those tokens can create grants within their scope and remain valid after the creator’s admin checkout ends. See Checkout tokens.

Configure the common bsh settings for an admin permission. If it uses a checkout API token, that token must allow the admin role. Use these scripts:

checkout.sh

#!/bin/sh
exec bsh checkout bridge --method admin-session

checkin.sh

#!/bin/sh
exec bsh checkin bridge --method admin-session

The method selects Bridge mode automatically and requires no target credentials. Checkin removes the admin checkout.

In the web interface, admins get Admin controls for deployment status, licensing, API tokens, telemetry, and effective configuration. They can also review or control live sessions and revoke share links. See Operations for the console and Live sessions and sharing for oversight.

Live-session control (admins always; auditors only for actions in their controls). The path uses the session id, not the transaction id, and takes no body. Send your session cookie, as the share calls below do:

terminal

curl -X POST https://bridge.example.com/api/sessions/<session_id>/lock -b cookies.txt        # -> {"session_id":"…","locked":true}
curl -X POST https://bridge.example.com/api/sessions/<session_id>/unlock -b cookies.txt      # -> {"session_id":"…","locked":false}
curl -X POST https://bridge.example.com/api/sessions/<session_id>/disconnect -b cookies.txt  # -> {"session_id":"…","disconnected":true}

Session control is a licensed feature. In limited mode all three calls return 403 and say to install a license.

Share links (the session owner or an admin). A share is view-only and can never outlive the underlying checkout:

terminal

# Issue (returns an opaque token + a ready-to-send watch URL)
curl -X POST https://bridge.example.com/api/sessions/<session_id>/share -b cookies.txt
# List
curl https://bridge.example.com/api/sessions/<session_id>/shares -b cookies.txt
# Revoke one (?token=…) or all (omit the token)
curl -X DELETE "https://bridge.example.com/api/sessions/<session_id>/share?token=<token>" -b cookies.txt

Last updated on November 6, 2026

Payload Reference