> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitwarden Vault: Sync Secrets to the Gateway

> Sync secrets from Bitwarden into Buckle. Agents can use vault items through the gateway without the Bitwarden CLI or direct API calls to Bitwarden.

Connect your Bitwarden vault to Buckle so the gateway can fetch credentials at request time, without storing them on the server. For an overview of all supported vault integrations, see [External Vaults](/docs/vaults/overview.md). Uses the [Bitwarden Agent Access SDK](https://github.com/bitwarden/agent-access) for encrypted communication.

![Bitwarden vault connection in the Buckle dashboard](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/connections-bitwarden.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=08bf0e4013079a73be2cf26ee50d8fc5)

> [!NOTE]
>
> This integration is in beta. The Agent Access SDK is under active development, so some details can change between releases.

## Prerequisites

* Buckle running locally or via Docker
* [Bitwarden Agent Access CLI](https://github.com/bitwarden/agent-access/releases) (`aac`) installed
* A Bitwarden account with credentials stored as login items

## Setup

**1. Start the Bitwarden listener**

Run the `aac` CLI to generate a pairing code:

```bash theme={null}
aac listen --psk
```

This prints a pairing code (two 64-character hex strings joined by `_`). Keep this terminal open.

**2. Pair in the dashboard**

Open the Buckle dashboard, go to **Settings** > **Apps** > **Vaults**, and click **Connect** on the **Bitwarden** card. Paste the pairing code and click **Connect Vault**.

The gateway establishes an encrypted Noise protocol session with your Bitwarden app through a WebSocket relay.

**3. Test it**

Make a request through the gateway with your agent's access token:

```bash theme={null}
curl -x http://x:YOUR_AGENT_TOKEN@localhost:10255 https://api.anthropic.com/v1/messages
```

If your Bitwarden vault has a login item with `api.anthropic.com` as the URI, the API key (stored in the password field) will be injected automatically.

## How credentials are matched

The gateway asks Bitwarden for credentials by domain. Bitwarden matches against the URI field of your vault items and returns the password field.

The injection rule depends on the target host:

| Host | Header | Format |
| - | - | - |
| `api.anthropic.com` | `x-api-key` | Raw value |
| All other hosts | `Authorization` | `Bearer <value>` |

> [!TIP]
>
> Store your API keys in the **password** field of Bitwarden login items. Set the URI to the API hostname (e.g. `api.anthropic.com`, `api.openai.com`).

## Session behavior

Sessions are restored automatically after a gateway restart. The first credential request triggers a reconnection using the stored session state from the database. There is no startup delay.

Sessions unused for 30 minutes are evicted from memory. The next request restores them automatically.

If a session can't be restored (e.g. the Bitwarden app was reinstalled), disconnect in the dashboard and pair again with a new code.

## Configuration

| Variable | Default | Description |
| - | - | - |
| `BITWARDEN_PROXY_URL` | `wss://ap.lesspassword.dev` | WebSocket relay for the Bitwarden Remote Access protocol |

## Troubleshooting

> [accordion] Pairing fails with 'PSK pairing failed'
>
> Make sure the `aac listen --psk` terminal is still running and the pairing code hasn't expired. Generate a fresh code and try again.

> [accordion] Credentials not injected after gateway restart
>
> The first request after restart triggers a lazy session restore. If it fails, the session state may be stale. Disconnect in the dashboard and re-pair.

> [accordion] 'unknown device' prompt on the aac side
>
> The `aac` CLI may prompt you to approve credential requests from the gateway. Press `y` to allow. This is a security feature of the Bitwarden Agent Access protocol.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.