Payload Reference

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

Creating a checkout


Method / Path	`POST /api/transactions`
Who can call it	Administrators only. Authenticate with an admin session, or - for server-to-server automation - the cluster shared-secret header `X-Bridge-Cluster-Token`.
Body	`application/json` (fields below)
Success	`201 Created` → `{"status":"created","transaction_id":"…"}`

There is no static “admin API key.” A caller is treated as an administrator when they hold an admin session (from your identity provider) or present the cluster token. See Authentication.

Required for every checkout

Field	Type	Description
`transaction_id`	string	Your unique ID for this checkout. Used to fetch or revoke it later, and in connect URLs.
`username`	string	The Britive user identity this checkout is for (the person connecting).
`expires_at`	integer	Expiry as a Unix timestamp (seconds). After this, connections are refused and the grant is reaped.

Required for an access (`user`) checkout

Field	Type	Description
`protocol`	string	What to connect with: `ssh`, `telnet`, `rdp`, `vnc`, `k8s` (alias `k8sexec`), `http`, `mysql`, `postgres`, `cockroachdb`, `mssql`, `redis`, `mongodb`, `cassandra`, `netconf`, `restconf`, `winrm`.
`target_host`	string	The backend host/IP to reach (not required for `http`).
`target_username`	string	The backend account to log in as (not required for `vnc` or `http`).
`target_port`	integer	Backend port. Optional - defaults per protocol (see Protocol Reference).

Common options (any access checkout)

Field	Type	Default	Description
`record_session`	boolean	`true`	Record this session. Send `false` to opt out (also disables live-view for it).
`token`	string	-	Per-checkout credential issued by the Britive platform; enables token-authenticated connect/review flows. Stored hashed; never returned.
`native_auth`	string	server default	How the connecting user proves who they are to Bridge for native connections: `ldap` or `bridge_credentials`.
`bridge_auth_password`	string	-	Required when `native_auth: bridge_credentials` - the credential the user presents to Bridge. Encrypted at rest; never returned.

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.

Field	Type	Applies to	Description
`target_password`	string	rdp (optional), vnc, all databases, restconf, winrm; optional for ssh	Backend password.
`private_key`	string (PEM)	ssh, netconf	Private key for key-based backend login (use this or `target_password`).
`user_public_key`	string	ssh	The connecting user’s public key, used to authenticate them to Bridge for native SSH.
`target_domain`	string	rdp	Windows/AD domain.
`kube_bearer_token`	string	k8s	Bearer token for the Kubernetes API (use this or the client cert pair).
`kube_client_cert` / `kube_client_key`	string (PEM)	k8s	Client certificate + key for mTLS to the Kubernetes API.
`target_ca_cert`	string (PEM)	databases, http	CA certificate to trust for the backend’s TLS.

Database options

Field	Type	Applies to	Description
`target_database`	string	mysql, postgres, mssql, redis (db index), cassandra (keyspace)	Default database to connect to.
`target_tls`	boolean	mysql, postgres, mssql	Connect to the backend over TLS (e.g. RDS/Aurora).
`target_tls_skip_verify`	boolean	databases, http	Don’t verify the backend’s TLS certificate. Use only when you can’t supply a CA.

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.

Field	Type	Default	Description
`rdp_security`	string	`any`	Security mode: `any`, `nla`, `tls`, or `rdp`.
`rdp_ignore_cert`	boolean	`false`	Skip backend RDP certificate validation.
`rdp_enable_drive`	boolean	`false`	Allow file copy via a redirected virtual drive.
`rdp_disable_copy`	boolean	`false`	Block copying out of the session (also applies to VNC).
`rdp_disable_paste`	boolean	`false`	Block pasting into the session (also applies to VNC).
`rdp_clipboard_save_files`	boolean	`false`	Save the content of copied files to the recording (otherwise only metadata is logged).
`rdp_clipboard_max_file_mb`	integer	`100`	Maximum size of a single clipboard file (MB).
`lock_blocks_screen`	boolean	`false`	When a reviewer locks the session, cover the screen instead of just blocking input.
`rdp_color_depth`	integer	`16`	Color depth: 8, 16, 24, or 32.
`rdp_server_layout`	string	`en-us-qwerty`	Keyboard layout.
`rdp_timezone`	string	-	IANA timezone for the session clock (e.g. `America/New_York`).
`rdp_enable_wallpaper`, `rdp_enable_theming`, `rdp_enable_font_smoothing`, `rdp_enable_full_window_drag`, `rdp_enable_desktop_composition`, `rdp_enable_menu_animations`	boolean	`false`	Visual-fidelity toggles (off by default for performance).
`rdp_disable_bitmap_caching`	boolean	`false`	Turn off bitmap caching (caching is on by default for performance).

Kubernetes (k8s) options

Field	Type	Default	Description
`kube_api_server`	string	-	Required. Kubernetes API address, e.g. `k8s-api:6443`.
`kube_namespace`	string	`default`	Target namespace.
`kube_container`	string	-	Target container (defaults to the pod’s main container).
`kube_command`	array	-	Command to run, e.g. `["/bin/bash"]`. Empty attaches to the running process instead.
`kube_tty`	boolean	`false`	Allocate an interactive terminal.

Web (HTTP proxy) options

Field	Type	Description
`capture_hosts`	array	Exact hostnames the user may reach through the proxy. Supply this and/or `capture_subdomains`.
`capture_subdomains`	array	Domain suffixes the user may reach (matches the domain and any subdomain).
`blocked_methods`	array	HTTP methods to deny, e.g. `["DELETE","PUT"]` (`CONNECT` can’t be blocked).
`sanitize_headers_extend`	array	Adds header names to the recording’s redaction list for this checkout.
`sanitize_query_params_extend`	array	Adds query-parameter names to redaction.
`sanitize_body_fields_extend`	array	Adds JSON body field names to redaction.

The sanitize_*_extend lists only add to the server’s base redaction lists - a checkout can never remove something the server already masks. Requests to a host not in your capture lists are blocked. See HTTP Proxy.

Command filtering (shell protocols)

Available for ssh, k8s, netconf, winrm, and restconf. Use an allowlist or a denylist (names and/or regular expressions).

Field	Type	Description
`allowed_commands`	array	Only these base commands may run.
`blocked_commands`	array	These base commands are rejected.
`allowed_patterns`	array	Regex allowlist.
`blocked_patterns`	array	Regex denylist (e.g. `"rm\\s+-rf"`).

Command filtering is not a security control. It is a convenience guardrail and an audit aid - a way to nudge well-intentioned users away from obvious mistakes and to flag notable commands in the recording. It must not be relied upon to prevent malicious or accidental damage to a target system.

Filtering inspects the command line as it is entered. Any user who reaches an interactive shell can defeat it through routine, well-understood techniques - subshells and pipelines, shell built-ins and aliases, scripts and interpreters (python, perl, sh -c …), an editor’s or pager’s shell escape, alternate paths or renamed binaries, and encoded or obfuscated input, among many others. Treating a command allow/deny list as a boundary would give a false sense of protection.

Protecting a target is the job of controls the target itself enforces: least- privilege accounts provisioned per checkout, network segmentation, the target OS/application’s own authorization, and time-boxed, fully recorded access. Use command filtering to complement those controls and improve the audit trail - never as a substitute for them.

Recording redaction override

Field	Type	Default	Description
`redact_response_bodies`	boolean	inherits server default	For `winrm` and `restconf`, force-on or force-off masking of secrets in recorded response/output bodies. Omit to inherit the server default.

Checking in (revoking)


Method / Path	`DELETE /api/transactions/{transaction_id}`
Who can call it	Administrators only.
Success	`200 OK` → `{"status":"deleted","transaction_id":"…"}`

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:

terminal

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

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

Last updated on July 6, 2026

Roles: user, auditor, admin