Checkout tokens

Checkout tokens let automation, scripts, and brokers create and check in Bridge checkouts through the HTTPS API. They are available in v3.0.2 and later and are disabled by default.

These credentials manage checkouts. They do not sign users in or authenticate to recording, monitoring, or token-management endpoints. For read-only monitoring, use service tokens. A checkout token is also separate from the per-checkout token field in the payload reference.

Before you begin

• Serve Bridge over HTTPS and allow the API client to reach that address.
• Sign in with active admin access, such as an admin checkout, to manage tokens.
• Provide a secret store or protected file for the client to read the token.

Enable checkout tokens

Add these settings to your Bridge configuration:

server:
  checkout_api_tokens:
    enabled: true
    max_token_days: 90

Roll out the configuration to every serving replica. Environment overrides are BRIDGE_SERVER_CHECKOUT_API_TOKENS_ENABLED and BRIDGE_SERVER_CHECKOUT_API_TOKENS_MAX_TOKEN_DAYS.

If a load balancer terminates HTTPS, keep server.secure_cookies: true and restrict access to the plaintext backend. Bridge refuses checkout token access when both server TLS and secure cookies are disabled.

max_token_days sets the maximum and default lifetime for new tokens. Its default is 90, and valid values are 1 to 36500. Changing the limit does not change existing expiration dates. See the configuration reference.

Create a checkout token

A token remains valid after its creator’s admin checkout ends. Further token management requires active admin access.

Configure the client

For bsh, supply the token through BSH_BRIDGE_BROKER_API_TOKEN, either directly or as a secret reference. A protected file is also supported through BSH_BRIDGE_BROKER_API_TOKEN_FILE. The external broker guide covers the HTTPS URL, CA trust, and permission variables.

Other API clients send the token in X-Bridge-Broker-Token. The checkout API reference lists the allowed routes. Tokens do not authorize other API operations.

Verify

Request a permission within the token’s scope. Confirm that the intended user receives the expected access, then check in the permission and confirm that access ends. For bsh, follow the broker verification steps.

For an API-only client, GET /api/broker/validate returns the token’s checkout group, roles, and protocols. GET /api/transactions lists its active checkouts within scope. Validation alone does not test target connectivity or cleanup.

Each independently created token owns an isolated checkout group. It cannot inspect or check in another group’s checkouts, including those created by the colocated broker. Replacing a token preserves its group.

Replace a token

Replace an active token before it expires:

1. Expand its name under Checkout tokens and select Replace.
2. Give the replacement a unique name and an expiration. Review the role, protocol, and network restrictions copied from the original token.
3. Select Create and save the replacement token from the dialog.
4. Update the client’s token source and repeat the verification.
5. After checkout and checkin succeed, select Revoke for the old token.

Replace preserves the checkout group so the replacement can manage existing checkouts within its scope. Creating an unrelated token starts a different group.

Revoke a token

If access must end now, check in the token’s existing checkouts before revoking it. Revoking the token alone does not end those checkouts.

Expand the token’s name under Checkout tokens and select Revoke. Revocation and expiration stop subsequent requests on every replica without a restart. Already-authorized requests can finish. Existing checkouts keep their own expiration.

Disable checkout tokens

Set server.checkout_api_tokens.enabled: false and roll out the configuration to every serving replica. Stored tokens remain available if the feature is re-enabled, subject to their expiration and revocation. Existing checkouts keep their own expiration.

Troubleshoot