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.

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.

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.

Prompt for the password at connect time. RDP is the one protocol where target_password is optional. Omit it and the browser session prompts the user for their password when they connect, sending it straight to the target (Bridge doesn’t store it). This suits “log in as yourself” flows - e.g. a Windows/AD account where the user knows their own password. The target must accept password authentication for that account. This prompt is browser-only; native RDP clients have no equivalent.

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

Roles: user, auditor, admin