|
The Bitwarden steps on this page are a summary, and Bitwarden may change them at any time. The definitive instructions are the ones in the Bitwarden help: https://bitwarden.com/help/cli/ |
SyncBackPro can retrieve logins, passwords, secure notes and SSH keys from Bitwarden. It uses the Bitwarden CLI (bw.exe), a free and open source program from Bitwarden, and signs in with the personal API key of your Bitwarden account.
This is for Bitwarden Password Manager, the vault you use in the Bitwarden apps and browser extensions. It works with every Bitwarden plan, including the free personal plan. Bitwarden Secrets Manager is a separate Bitwarden product, and it cannot be used.
What You Need
•A Bitwarden account that is used only by SyncBackPro and holds just the items it needs. See Why the Master Password Is Stored below. The account must have a master password. Accounts that sign in with single sign-on (SSO) and trusted device encryption, or through Key Connector, have no master password and cannot be used.
•The personal API key of that account (see step 2).
•The Bitwarden CLI for Windows, version 2024.7.0 or later, from the Bitwarden download page. Nothing else needs to be installed to run it.
•64-bit Windows. The Bitwarden CLI is only available for 64-bit Windows.
•Internet access to the Bitwarden server from the computer running SyncBackPro, either directly or through a proxy server (see Proxy Servers below).
Step 1: Install the Bitwarden CLI
On the Bitwarden download page, find the Command Line Interface section and download the Windows version. It is a zip file that contains a single program, bw.exe. Extract it and save it somewhere every user account that runs your profiles can read, e.g. C:\Program Files\Bitwarden CLI\bw.exe. To check that it works, open a command prompt and run:
"C:\Program Files\Bitwarden CLI\bw.exe" --version
It should print a version number.
Before it runs bw.exe, SyncBackPro checks that the file carries Bitwarden's own digital signature. It will not run any other program.
Give bw.exe a folder of its own. Do not save it in a folder that also contains a folder called bw-data. The Bitwarden CLI would keep its data in that folder instead of the private folder that SyncBackPro gives it, so SyncBackPro refuses to run it.
Step 2: Get the Personal API Key
Log in to the Bitwarden web vault with the account that SyncBackPro will use. This is https://vault.bitwarden.com for an account on Bitwarden's US servers, https://vault.bitwarden.eu for one on its EU servers, or the address of your own server. Then:
1.Go to Settings, then Security, then the Keys tab.
2.Click View API key and enter the master password.
3.Copy the client_id and the client_secret. The client_id starts with user.
This is the personal API key of the account. The API key of a Bitwarden organisation, from the organisation's own settings, cannot be used. See Personal API Key for CLI Authentication in the Bitwarden help for more details.
Treat the client_secret as you would a password. If you rotate the API key, the old one stops working and you must modify the connection in SyncBackPro.
Step 3: Create the Connection
In SyncBackPro, go to the Secrets Manager (via the main burger menu), go to the Connections page, click Create and choose Bitwarden. You are then asked for:
Name: The name you want to give to the connection. This is for your reference.
Path to bw.exe: Where you saved the Bitwarden CLI in step 1. If you leave it blank then SyncBackPro looks for bw.exe on the path.
Server: Choose https://vault.bitwarden.com (the default) for an account on Bitwarden's US servers, or https://vault.bitwarden.eu for one on its EU servers. For your own self-hosted Bitwarden or Vaultwarden server, enter its address. The address must start with https://.
client_id: The client_id from step 2, starting with user.
client_secret: The client_secret from step 2.
You are then warned that the master password will be stored with the connection (see below). Click OK to continue, and you are asked for:
Bitwarden Master Password: The master password of the account.
SyncBackPro connects immediately and lists the items in the vault, so you will know straight away if any of the details are wrong. This can take several seconds. You then create secrets that use the connection in the usual way, as described in Secrets Manager.
Why the Master Password Is Stored
The API key only logs in to Bitwarden. Everything in a Bitwarden vault is encrypted, and only the master password can decrypt it, so SyncBackPro needs the master password as well. The client_id, client_secret and master password are stored, encrypted, in the SyncBackPro settings, in the same way as the credentials of any other connection.
This means that anyone who can decrypt the SyncBackPro settings could open the whole vault. We strongly recommend a dedicated Bitwarden account that holds only the credentials your backup profiles need. A tidy way to do this is to keep those items in a collection of a Bitwarden organisation, and share that collection with the dedicated account.
If you change the master password, or rotate the API key, modify the connection and enter the new details.
Two-step login on the account does not stop SyncBackPro from signing in. Bitwarden does not ask for it when the API key is used.
Which Items Can Be Used
•Logins: you choose whether the secret is the username, the password, or a custom text or hidden field of the item. A custom field is listed as field:name, where name is the name of the field. An empty password is used as an empty password.
•Secure Notes: the whole text of the note is used.
•SSH Keys: you choose whether the secret is the privateKey or the publicKey of the item. For example, the private key can be used for SFTP.
Cards and identities are not listed, and items in the trash are ignored.
Items are listed by their name. The name must match exactly, including upper and lower case. Give each item a unique name. If items of different kinds have the same name, a login is used before a secure note, and a secure note before an SSH key. Two items of the same kind with the same name, for example two logins, are refused with an error rather than guessed at, because the username and password could otherwise come from different items.
Renaming an item breaks the profiles that use it. SyncBackPro remembers a Bitwarden item by its name and nothing else. If you rename the item in Bitwarden, every profile that uses that secret fails with Secret does not exist until you modify the secret in the Secrets Manager and select the item under its new name. The same happens if the item is deleted, or is no longer shared with the account.
Also, if you give a different item the old name, SyncBackPro will use that item from then on, without any warning. So once an item is used by a profile, do not rename it, and do not reuse its old name for anything else.
Elevated, Scheduled and Administrator Protection
SyncBackPro does not use any Bitwarden login stored in your Windows profile. Each time it connects it gives the Bitwarden CLI its own private temporary folder, which is deleted afterwards. A Bitwarden connection therefore works in the same way when SyncBackPro is run normally, run elevated, run under Administrator Protection, or run from a scheduled task, including one that runs whether or not the user is logged on. The account the profile runs as must be able to reach the Bitwarden server.
Each connection also has its own device identity. Bitwarden sees the same device every time, not a new device (and a new device email) on every profile run.
Proxy Servers
The Bitwarden CLI ignores the Windows proxy settings. It only uses an HTTP proxy server if the HTTPS_PROXY environment variable is set for the Windows account the profile runs as, e.g. http://proxy.example:8080. If the proxy server needs a user name and password, include them, e.g. http://user:[email protected]:8080.
If the Bitwarden CLI cannot reach the server, the error from SyncBackPro says so and reminds you about HTTPS_PROXY.
Security
•The client_id, client_secret and master password are stored, encrypted, in the SyncBackPro settings. The value of a secret is never stored locally nor shown to the user.
•Together, the API key and the master password open the whole vault. This is why you should use an account that holds only the items SyncBackPro needs.
•To stop SyncBackPro retrieving secrets, rotate the API key of the account in the Bitwarden web vault. If you think someone else may know the master password, change it as well.
•SyncBackPro only gives the credentials to a bw.exe that carries Bitwarden's own digital signature.
•While a profile runs, an encrypted copy of the vault is kept in a temporary folder, so that all the Bitwarden secrets the profile uses can share one connection. It is deleted when the profile finishes.
Limitations
•SyncBackPro only reads from Bitwarden. It never creates, changes or deletes items.
•Every profile run that uses a Bitwarden secret signs in to Bitwarden and downloads the vault, which takes several seconds and needs Internet access. This happens once per run for each connection, not once per secret, as the secrets of a run share one connection.
•Accounts with no master password (single sign-on with trusted device encryption, or Key Connector) cannot be used, and nor can organisation API keys.
•Bitwarden Secrets Manager, a separate Bitwarden product, cannot be used.
•Cards and identities cannot be used.
•Items are found by their name only, so renaming an item in Bitwarden breaks every profile that uses it until the secret is selected again. See Which Items Can Be Used above.
Troubleshooting
An error reported by the Bitwarden CLI itself is shown after The Bitwarden CLI failed (exit code ...). The most common errors are:
client_id or client_secret is incorrect: the API key is wrong, or it has been rotated. Also check the server: an account on Bitwarden's US servers does not exist on its EU servers, and the other way round. Modify the connection and enter the current details.
Bitwarden could not unlock the vault: the master password is wrong: the master password is wrong, or it has been changed in Bitwarden. Modify the connection and enter the current master password. Accounts with no master password (SSO with trusted devices, or Key Connector) cannot be used.
Insecure URL not allowed or The Bitwarden server must be an https:// address: the server address starts with http://. Use an https:// address.
The Bitwarden CLI (bw.exe) was not found: the path in the connection is wrong, or it is blank and bw.exe is not on the path. If SyncBackPro is run as another user, e.g. from a scheduled task, check that user can read the file.
The Bitwarden CLI is version ...: the Bitwarden CLI is older than version 2024.7.0. Download the latest version.
... is not the Bitwarden CLI as signed by Bitwarden: the credentials unlock your whole vault, so SyncBackPro only gives them to a bw.exe that carries Bitwarden's own digital signature. The file has been changed or damaged, or is a different program. Download the Bitwarden CLI again. While a profile is using the Bitwarden CLI, bw.exe cannot be replaced, so update it when no profiles are running.
The Bitwarden CLI would use the bw-data folder beside ...: there is a folder called bw-data in the same folder as bw.exe. Put a copy of bw.exe in a folder of its own and change the path in the connection.
The Bitwarden CLI needs 64-bit Windows: Bitwarden does not provide the CLI for 32-bit Windows, so Bitwarden cannot be used on this computer.
The Bitwarden CLI did not finish within 120 seconds, or a network error such as ECONNREFUSED, ETIMEDOUT or ENOTFOUND: the computer, or the account the profile runs as, cannot reach the Bitwarden server. Check the Internet connection, the firewall and the server address. If the computer reaches the Internet through a proxy server, set HTTPS_PROXY as described in Proxy Servers above.
More than one Bitwarden login is called ...: two items of the same kind have the same name. Rename one of them so that every name is unique, then, if needed, modify the secret in the Secrets Manager and select the item again.
Secret does not exist: the item has been renamed or deleted in Bitwarden, or is no longer shared with the account. Modify the secret in the Secrets Manager and select the item again.
No secrets found: the account has no logins, secure notes or SSH keys. Check that the items have been shared with the account.
See also: Secrets Manager
All Content: 2BrightSparks Pte Ltd © 2003-2026