Connect to a Bitwarden server

Android · Wear OS · Linux · macOS · Windows
View Markdown

To add a Bitwarden account, sign in to its server: the official bitwarden.com or bitwarden.eu cloud, or a self-hosted server such as Vaultwarden. On a Wear OS watch, follow Set up Keyguard on the watch instead.

Sign in

  1. In Settings, select Add account, then Bitwarden.
  2. Select United States, Europe or Custom (self-hosted). For a self-hosted server, fill in the Server fields.
  3. Enter the Email and Password you use in the web vault.
  4. Select Sign in. If your account uses two-factor authentication, enter the second factor. Keyguard adds the account and syncs its items.

For the second-factor options, see Two-factor authentication.

Server fields

These fields appear when you select Custom (self-hosted). Usually, Server URL is enough.

FieldValue
Server URLThe base URL of your server.
Web Vault Server URLEmpty means the Server URL.
API Server URLEmpty means the Server URL plus api/.
Identity Server URLEmpty means the Server URL plus identity/.
Icons Server URLEmpty means the Server URL plus icons/.
Notifications Server URLEmpty means the Server URL plus notifications/.
Client certificateImport a PKCS#12 (.p12 or .pfx) file if your HTTPS server requires mutual TLS. Enter the file password when prompted.
HTTP headersHeaders sent with every request to the server, for a reverse proxy that expects them. Select Add more for each header, and enter its Key and Value.

The client certificate is saved with the encrypted account. Its import password is discarded. For an existing account, open Settings > Accounts, select the account, then choose Security > Client certificate. Add or replace the certificate, check its details, and select Save. Removing it asks for confirmation and applies at once. You can make changes while offline; Keyguard then queues a sync. Changes leave your account and vault data intact. Active transfers may finish with the previous certificate.

On Wear OS, import the certificate while adding the account from your phone. Editing a watch account’s certificate is not supported.

Sign-in steps that open in your browser, such as SSO, can’t use the certificate saved in Keyguard. Install the certificate on your device or in your browser as well.

For example, to pass Cloudflare Access, create a service token in Cloudflare and add two headers:

KeyValue
CF-Access-Client-IdThe token’s client ID
CF-Access-Client-SecretThe token’s client secret

Sign in with SSO

  1. In Settings, select Add account, then Bitwarden.
  2. Select your server.
  3. Enter your Email.
  4. Select Log in with SSO. Your browser opens the web vault’s SSO page.
  5. Sign in, then return to Keyguard.
  6. Enter your master password, and select Continue. Accounts that use Key Connector skip this step.

Keyguard doesn’t support trusted device encryption. An account that needs it shows an error and points you to the web vault.

Find the server from your email

If your organization publishes its server in DNS, Keyguard can fill it in.

  1. Enter your Email.
  2. Select Auto-discover server. Keyguard looks up your email domain and shows “Server set to” with the address it found.
  3. Check the address, then sign in.

The button appears for your own domains, not for public mail providers. Keyguard looks up the domain only when you select it. On Android, discovery needs Android 10 or newer.

Publish a server in DNS

For server admins: add a TXT record named _bitwarden or _vaultwarden under your email domain. Its value is the server’s https:// URL, with an optional port and path, and no query or fragment.

_bitwarden.example.com.  IN  TXT  "https://vault.example.com"

Pass a captcha

If the server asks for a captcha, Keyguard shows a Client secret field.

  1. In the Bitwarden web vault, open Settings > Security > Keys and view your API key.
  2. Copy the client_secret value.
  3. In Keyguard, enter it in Client secret.
  4. Select Sign in.