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.

user checkout - native SSH, key auth, command filtered

curl -X POST https://bridge.example.com/api/transactions \
  -H "X-Bridge-Cluster-Token: $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn-ssh-001",
    "role": "user",
    "protocol": "ssh",
    "username": "alice@corp",
    "target_host": "10.0.4.21",
    "target_port": 22,
    "target_username": "ec2-user",
    "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----",
    "user_public_key": "ssh-ed25519 AAAAC3Nz... alice",
    "record_session": true,
    "allowed_commands": ["ls", "cat", "grep"],
    "blocked_patterns": ["rm\\s+-rf"],
    "expires_at": 1750000000
  }'

More payloads: Examples by protocol.

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 a token and an audit_scope.

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.

auditor checkout - full scope, live-view + all controls

curl -X POST https://bridge.example.com/api/transactions \
  -H "X-Bridge-Cluster-Token: $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn-aud-006",
    "role": "auditor",
    "username": "frank@corp",
    "token": "AUDITOR-TOKEN-FROM-BRITIVE",
    "audit_scope": {
      "users": ["*"],
      "protocols": ["ssh", "rdp"],
      "targets": ["*.prod.corp", "10.0.0.0:22"],
      "target_usernames": ["root", "Administrator"],
      "artifacts": ["recording", "har", "queries"],
      "allow_live_view": true,
      "controls": ["lock", "unlock", "disconnect"]
    },
    "expires_at": 1750000000
  }'

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. An administrator can create and 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.

Administrator status normally comes from your identity provider (an admin group mapped at login). You can also grant an identity admin powers for a bounded window by issuing an admin-role checkout:

admin checkout - grant admin for the checkout lifetime

curl -X POST https://bridge.example.com/api/transactions \
  -H "X-Bridge-Cluster-Token: $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn-admin-007",
    "role": "admin",
    "username": "grace@corp",
    "expires_at": 1750000000
  }'

In the web interface: admins get the Admin console (the floating Admin button) with three tabs - Overview (deployment topology, live sessions, usage statistics), License (install / activate / remove without a restart), and View Configuration (read-only effective config, secrets omitted) - plus full oversight: watch or control any live session and revoke any share link. See Operations for the console and Live Sessions & 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:

terminal

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

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 July 6, 2026

Payload Reference