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


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.
`ldap_auth_passthrough`	boolean	`false`	Sign in to the backend with the user’s own directory identity instead of a stored credential. See directory credential passthrough for the protocols it covers and what it implies.
`bridge_prompt_kb_layout`	string	`us`	Keyboard layout Bridge uses to read what is typed into its own in-session prompts (`us` or `uk`). Only affects native RDP sign-in forms, where Bridge interprets the keystrokes itself - set it when your users’ keyboards are not US, or a masked password will be mistyped.
`paste_capture`	string	server default	What a paste into a browser session records: `full` (verbatim), `redacted` (secret-shaped spans masked), or `metadata` (size, line count and timing only). Overrides `recording.paste_capture`.
`keystroke_capture`	string	server default	What typed input in a desktop (RDP/VNC) session contributes to Activity Search and SIEM export: `redacted` (secret-shaped spans masked) or `off`. Does not change the recording, which captures key events either way. Overrides `recording.keystroke_capture`.

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.

Protocol	How the backend logs in
Native RDP	The directory password, giving a silent Windows logon (no sign-in form).
Native SSH	The directory password - used only when the checkout carries no `private_key` and no `target_password`.
Native NETCONF	Offered after the checkout’s own credentials, so an explicit one always wins.
Native PostgreSQL / CockroachDB	The directory password, which the target must accept (`ldap`, `password` or `md5` in `pg_hba.conf`; `scram-sha-256` is not supported).
Native SQL Server	Windows Authentication. The password is used to compute the logon response and is never sent to the target.

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.

What to know before enabling it.

It applies to native connections only. Browser users authenticate to the web UI, so Bridge never holds their password.
It requires native_auth: ldap (the default when LDAP is enabled). A bridge_credentials password or a per-checkout token is a Bridge-managed secret and is never forwarded - the checkout is rejected at creation if it asks.
Setting it on a protocol that does not support it is rejected when the checkout is created, rather than silently ignored.
Database checkouts require the client to connect with encryption. Enabling passthrough is what makes the database listener authenticate the connecting user, and it will not read a password off an unencrypted connection - sslmode=require for PostgreSQL, Encrypt=yes for SQL Server. Database checkouts without the flag are unchanged.
SQL Server targets must not enforce Extended Protection for Authentication (channel binding), which is off by default. Because Bridge terminates the user’s connection and opens its own to the target, channel binding cannot match and the logon is refused. Use a stored target_password for those targets.
Azure SQL is not covered - its Entra ID authentication is token-based.
The target’s directory must be the one Bridge authenticates against, or trust it. Otherwise every session is a failed backend logon, and repeated failures count toward account-lockout policy.

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	vnc, all databases, restconf, winrm; optional for rdp and ssh	Backend password. Also optional wherever the checkout sets `ldap_auth_passthrough`.
`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, mssql	Windows/AD domain. On SQL Server it names the domain for Windows Authentication; you can instead put it in `target_username` as `DOMAIN\user` or `user@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.

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.

Passwordless RDP checkouts. RDP is one of the protocols where target_password is optional, for “log in as yourself” flows - e.g. a Windows/AD account where access comes from directory group membership rather than a stored account. Omit it and the user supplies the credential at connect time:

Browser sessions prompt for the password in the page when the user connects.
Native RDP clients get a sign-in form drawn inside the session before the Windows target is dialed - domain, user name and password, with Tab/Enter/Esc and the mouse. What is typed goes straight to the target; it is not stored, and it is not part of the session recording.
Either, if the checkout sets ldap_auth_passthrough, can skip the prompt entirely for native connections and sign in with the directory password the user already gave Bridge.

The target must accept password authentication for that account.

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 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:

Field	Type	Description
`allowed_commands`	array	Allowlist of base commands/keywords - only these may run.
`blocked_commands`	array	Denylist of base commands/keywords - these are rejected.
`allowed_patterns`	array	Regex allowlist, matched against the full command/query line.
`blocked_patterns`	array	Regex denylist, matched against the full line (e.g. `"rm\\s+-rf"`, `"DROP\\s+TABLE"`).

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. 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.)

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. Database query filtering inspects the parsed wire query, so it is harder to slip past than an interactive shell - but the same principle holds: it is a guardrail, not authorization.

Protecting a target is the job of controls the target itself enforces: least- privilege accounts provisioned per checkout (including scoped database roles and grants), network segmentation, the target OS/application’s own authorization, and time-boxed, fully recorded access. Use command and query 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 August 11, 2026

Roles: user, auditor, admin