Legacy checkout API helper

broker-bridge-api.sh is the legacy shell client for Bridge’s checkout API. It still ships with Bridge at /opt/britive-broker/scripts/broker-bridge-api.sh.

Use the latest bsh for new permissions with a supported provisioning method. bsh provisions target access, registers the checkout, and returns connection details. Its matching checkin method ends the checkout and revokes the target access.

The legacy helper submits API requests only. It does not create target accounts, rotate target credentials, or remove access on the target. Existing integrations must handle those operations themselves. It also supports direct JSON payloads and inspection operations that bsh does not provide.

Configuration

The helper requires a POSIX shell and curl. Global options precede the command:

broker-bridge-api.sh [global options] <command> [arguments]

Examples below use the short command name. The installed directory must be on PATH, or the command must use its full path.

Environment variable	Global option	Default
`BRIDGE_BROKER_API_URL`	`--api-url URL`	`http://127.0.0.1:8081`
`BRIDGE_BROKER_API_TOKEN_FILE`	`--token-file PATH`	`/data/keys/bridge-broker-api.token`
`BRIDGE_CA_CERT`	`--ca-cert PATH`	Unset. HTTPS uses the system’s trusted CAs.
`BRIDGE_TLS_INSECURE`	`--insecure true\|false`	`false`. Certificate verification is enabled.

The colocated broker inherits the API URL and token-file settings from Bridge. The helper reads the credential file for each request and sends its value in X-Bridge-Broker-Token. The credential must be nonempty and contain no control characters. A trailing newline in the file is removed.

External brokers use the public HTTPS API and a checkout token. An external configuration is:

export BRIDGE_BROKER_API_URL=https://bridge.example.com
export BRIDGE_BROKER_API_TOKEN_FILE=/run/secrets/bridge-checkout-token
export BRIDGE_TLS_INSECURE=false

The credential file must be readable by the broker’s operating-system user. BRIDGE_CA_CERT supplies a trusted CA bundle when the HTTPS endpoint uses a private CA. Plaintext requests are accepted only for the private loopback URLs http://127.0.0.1:8081 and http://localhost:8081.

The helper does not read BSH_BRIDGE_BROKER_API_TOKEN or resolve secret-manager references. BRIDGE_BROKER_API_TOKEN is not a supported environment input. If bsh and the helper share a token, the helper still needs the token’s raw value in its credential file.

Commands

Command	API request
`health`	`GET /api/broker/validate`
`admin-validate`	Alias of `health`.
`checkout-list`	`GET /api/transactions`
`checkout-get <transaction_id>`	`GET /api/transactions/{transaction_id}`
`checkout-create --file <payload.json>`	`POST /api/transactions` with the file’s JSON body.
`checkout-create --stdin`	`POST /api/transactions` with JSON from standard input.
`checkout-delete <transaction_id>`	`DELETE /api/transactions/{transaction_id}`

The helper prints the response body and exits successfully for any 2xx response. Transport failures and other HTTP statuses produce a nonzero exit code.

Submit a checkout

The JSON file contains a checkout payload with a unique transaction ID, future expiration, and the required target credentials:

broker-bridge-api.sh checkout-create --file checkout.json

Creation returns 201 Created. The helper does not generate missing payload fields. If the response is lost, checkout-get can inspect the transaction before a retry. Existing transaction IDs cannot be overwritten.

Inspect or check in a checkout

These commands use the same transaction_id as the original payload:

broker-bridge-api.sh checkout-get txn-example-001
broker-bridge-api.sh checkout-delete txn-example-001

Checkin removes the Bridge grant and ends its sessions. Any target account or credential cleanup remains the permission script’s responsibility.

External checkout tokens can inspect and manage only checkouts in their own group and scope. A replacement token retains the original token’s group.

Verify

These requests validate the broker credential and list its visible checkouts:

broker-bridge-api.sh health
broker-bridge-api.sh checkout-list

For an external checkout token, validation returns its pool identifier, allowed roles, and allowed protocols. Private broker validation returns 204 No Content. An empty response body alone does not indicate a failure.

When replacing a token used by the helper, its credential file must contain the replacement before verification. A token used by bsh separately must be updated in bsh’s configured token source too.

Move a permission to bsh

The Bridge permission examples pair each supported checkout method with its checkin method. The bsh Bridge setup guide covers target provisioning, identity mappings, and connection settings.

bsh replaces both target provisioning and checkout registration for its supported methods. Replacing only the API call in an existing provisioning script can create target access twice. Migration requires reviewing the complete checkout and checkin pair, then verifying that access starts and ends as intended.

Last updated on November 6, 2026

Connect an external broker