Migration Script
The Bitwarden public API allows administrators to automate administrative tasks using scripts. The script documented in this article is written to help Bitwarden customers migrate their existing setup from a previous Bitwarden Password Manager environment into a new organization, providing a way to migrate organization vault data, groups, and associated groups' and members' permissions to a new installation.
The script is written in Python and can be run on any operating system with Python v3 installed. Download the script and an example configuration file here.
Other than the default libraries shipped with most Python distributions included by default on Linux and macOS, and available for Windows), this script requires an additional module called requests be installed before the script can run successfully.
A common tool to install Python modules is called pip. To install the module using pip:
Bashpip3 install requests
note
pip3 - Some machines will have multiple versions of Python installed. Using pip3, instead of just pip, specifies that you install requests with Python v3. If your machine only has one Python version installed, use pip instead.
The above download contains two files:
bwAdminTools.py: This is the script you will need to execute migration. It requires a fully-configured configuration file.config-example.cfg: This is the configuration file required for migration, which you will need to create and setup before running the script.
Unpack the .zip and save these files to the same directory. Once you do, add the following files to the same directory:
Bitwarden Password Manager CLI native executable.
Before you can continue, you must create the destination organization that you'll be migrating to. Learn how to create an organization.
note
We recommend inviting users prior to running the migration script. Users must be in at least an invited state in order to migrate group and permissions settings.
Before running any bwAdminTools.py script functions, you will need to create a configuration file. Copy the contents of config-example.cfg into a new config.cfg file in the same directory, and fill in the following variables. Note that, as this is a migration script, variables are broken into Source and Destination groupings in this documentation:
Source organization variable | Variable description |
|---|---|
bw_vault_uri= | FQDN of your source web vault, e.g. https://company.bitwarden.com if you're self-hosting or https://vault.bitwarden.com if you're using US-based Bitwarden cloud services. |
bw_org_client_id= | Source organization API key client ID. Learn where to find it. |
bw_org_client_secret= | Source organization API key client secret. Learn where to find it. |
bw_org_id= | Source organization's GUID. Copy the |
bw_acc_client_id | Source organization admin's or owner's personal API key client ID. Learn where to find it. |
bw_acc_client_secret= | Source organization admin's or owner's personal API key client secret. Learn where to find it. |
Destination organization variable | Variable description |
|---|---|
dest_bw_vault_uri= | FQDN of your source web vault, e.g. https://company.bitwarden.com if you want to self-host or https://vault.bitwarden.eu if you want to use EU-based Bitwarden cloud services. |
dest_bw_org_client_id= | Destination organization API key client ID. Learn where to find it. |
dest_bw_org_client_secret= | Destination organization API key client secret. Learn where to find it. |
dest_bw_org_id= | Destination organization's GUID. Copy the |
dest_bw_acc_client_id= | Destination organization admin's or owner's personal API key client ID. Learn where to find it. |
dest_bw_ac_client_secret= | Destination organization admin's or owner's personal API key client secret. Learn where to find it. |
Once you've setup these variables, you're ready to start migration using the bwAdminTools.py script functions.
From the directory where you've stored your bwAdminTools.py file, config.cfg file, and Password Manager CLI executable, you can run the following commands:
note
python3 - Some machines will have multiple versions of Python installed. Using python3, instead of just python, specifies that commands run with Python v3. If your machine only has one Python version installed, use python instead. Some distributions will also have a python instead of python3 binary for v3.
To print script helper text:
Bashpython3 bwAdminTools.py -hTo compare source and destination organizations:
Bashpython3 bwAdminTools.py -c diffbwTo migrate organization vault data, groups, and groups' permissions from a source organization to a destination organization:
Bashpython3 bwAdminTools.py -c migratebwUsers must be in at least an invited state in the destination organization for
migratebwto be successful.To migrate members' permissions (outside of groups) from a source organization to a destination organization:
Bashpython3 bwAdminTools.py -c migratebwusersUsers must be in at least an invited state in the destination organization for
migratebwusersto be successful.To delete all collections from the source organization:
Bashpython3 bwAdminTools.py -c purgecolTo delete all collections from the destination organization:
Bashpython3 bwAdminTools.py -c purgecoldestTo delete all groups from the source organization:
Bashpython3 bwAdminTools.py -c purgegroupTo delete all groups from the destination organization:
Bashpython3 bwAdminTools.py -c purgegroupdest