Payload Reference

The complete field reference for POST /api/transactions. Jump to a section: required · credentials · databases · RDP · Kubernetes · HTTP · command & query filtering · check-in. For copy-paste payloads see Examples by protocol.

Creating a checkout

External checkout tokens

From v3.0.2, deployments with server.checkout_api_tokens.enabled: true accept X-Bridge-Broker-Token on the following HTTPS routes:

The credential determines ownership. The checkout payload does not select a broker group. Existing transaction IDs cannot be overwritten. The token cannot manage checkouts from another group or the colocated broker.

Checkout tokens are separate from the token field below, which authenticates access to an individual checkout. For creation, rotation, and network restrictions, see Checkout tokens.

Required for every checkout

Required for an access (user) checkout

Common options (any access checkout)

Directory credential passthrough

ldap_auth_passthrough covers the case where a target grants access by directory group membership, so there is no account for anyone to store. Instead of a vaulted credential, Bridge signs in to the backend with the directory identity the user already proved to it.

It is off by default and set per checkout: handing a user’s directory password to a target is a decision about that target, not something to assume.

A checkout that enables it may omit the credential its protocol would otherwise require - target_password, or private_key for SSH and NETCONF. target_username is still required: it names the backend account.

Browser password prompts

A browser RDP or Telnet session with no stored target password asks the user for one when the session starts. Browser SSH does the same when the checkout has no stored password or private key. Bridge sends the password in a POST request, encrypts it at rest, and binds it to a short-lived, single-use connect token. The session URL contains only the token, never the password.

Credentials (by protocol)

These are the secrets Bridge uses to reach the backend. They are encrypted at rest and never appear in any API response.

Database options

Three of these fields reach past the databases. WinRM requires HTTPS, and target_tls_skip_verify also applies to WinRM, RESTCONF, Kubernetes exec and the HTTP proxy. The Applies to column is authoritative; the section heading is not.

You can also restrict which queries a database session may run - see command & query filtering. See also the Databases protocol reference.

Remote-desktop (RDP) options

RDP exposes the richest per-checkout controls - this is how you turn clipboard and file copy on or off per grant. These apply to both modes; note that native RDP is in beta and certain RDP features may not yet function as expected there.

Kubernetes (k8s) options

Web (HTTP proxy) options

For HTTP bearer injection in v3.0.2, set target_password, an exact target_host, and an explicit target_port. The host must be a hostname or IP, without a URL scheme, path, or wildcard. Capture scope still applies. Bridge sends the credential only to that HTTPS host and port, replaces client Authorization and Host headers, and verifies the target certificate. target_ca_cert can supply a private CA. target_username is unused.

An empty target_password preserves client-supplied destination authentication. With a bearer token, HTTPS interception remains required even when recording is disabled. See Use kubectl through Bridge.

Command and query filtering

Restrict which commands (shell protocols) or queries (databases) a session may run, using an allowlist or a denylist of names and/or regular expressions. The same four fields drive both:

Set any allowed_* list and the session runs in allowlist mode (deny by default - only matches pass). Otherwise, set any blocked_* list for denylist mode (allow by default - only matches are rejected). Set neither to leave filtering off.

The two modes are exclusive, not layered. In allowlist mode the blocked_* lists are never consulted, so combining them does not add a second line of defence: the allowlist is the whole policy. Put everything you want refused outside the allowlist rather than in a blocked_* list beside it. A rejected command/query is refused and marked in the session recording; in an interactive terminal the line is cleared and a [BLOCKED] notice is shown.

Applies to:

• Shell protocols - ssh, telnet, k8s, netconf, winrm, restconf (native clients and in-browser terminals). The base “command” is the first word on the line (e.g. ls, kubectl).
• Databases - mysql, postgres, cockroachdb, mssql, cassandra, redis, mongodb. The base “command” is the leading query keyword (SELECT, INSERT, DROP, …); patterns match the full query text. (| is treated as a SQL operator, not a shell pipe.)

Recording redaction override

Checking in (revoking)

Revoking removes the grant so new connections are refused and any lingering session is reaped by the watcher. To immediately terminate connections that are still live, also call a disconnect endpoint:

Both endpoints require owner or administrator authority. Send the authenticated browser session cookie:

# End every live session for a checkout (by transaction id)
curl -X POST -b cookies.txt \
  https://bridge.example.com/api/auth/checkouts/<transaction_id>/disconnect

# End one specific session (by session id)
curl -X POST -b cookies.txt \
  https://bridge.example.com/api/auth/sessions/<session_id>/end

A signed-in owner or administrator can call either endpoint from the web interface instead, using their session cookie. A checkout’s own bearer token works for that checkout only.

Access paths and Oracle options

Oracle requires vaulted target credentials. Native Oracle also requires explicit native_auth: bridge_credentials and bridge_auth_password. Browser-only MongoDB needs no native Bridge password. See Oracle beta.

VNC beta options

VNC beta is opt-in for development and testing, disabled by default and not production-ready. Both access paths default to port 5900. The target requires a separate vaulted target_password of 1 to 8 bytes and does not use target_username. The Bridge or LDAP login password has no eight-byte limit and is never forwarded to the target.

Native viewers require VeNCrypt X509Plain and a trusted Bridge certificate. Use native_auth: bridge_credentials with bridge_auth_password, or native_auth: ldap for directory authentication. Deployment switches and checkout native_enabled and browser_enabled flags must permit the selected path.

target_tls: true performs TLS before the target RFB handshake and verifies the target hostname. target_ca_cert supplies a private CA. VNC refuses target_tls_skip_verify, anonymous target authentication, and command filtering. Clipboard transfer, file transfer, and live-view sharing are unavailable. See the VNC checkout example.