# Bitwarden Migration Guide

Export your Bitwarden vault as **JSON** (recommended) or **CSV** and import into DVE.

## Prerequisites

- Bitwarden web vault or desktop app access
- Organization export permission if migrating an org vault
- DVE **IT Admin** or **Super Admin** role
- Vault unlocked with master password or SSO session active

## Step-by-step export from Bitwarden

### Option A — JSON export (recommended)

1. Log in to **Bitwarden** (web vault at vault.bitwarden.com or desktop app).
2. Go to **Tools → Export Vault**.
3. Select file format **`.json`** (encrypted JSON is **not** supported by DVE — choose unencrypted JSON).
4. Enter your master password to confirm.
5. Save the `.json` file locally.

### Option B — CSV export

1. Log in to **Bitwarden**.
2. Go to **Tools → Export Vault**.
3. Select **`.csv`** format.
4. Confirm with your master password.
5. Save the `.csv` file locally.

JSON preserves item types, custom fields, and multiple URIs better than CSV.

## Item type mapping

| Bitwarden type | DVE `credential_type` |
|----------------|----------------------|
| Login (type `1`) | `login` |
| Secure Note (type `2`) | `secure_note` |
| Card (type `3`) | `credit_card` |
| Identity (type `4`) | `identity` |
| Unknown / other | `other` |

## Custom fields handling

Bitwarden **Login** items may include a `fields` array with name/value pairs. DVE imports these as **`custom_fields`** on the credential record.

## DVE field mapping

| Bitwarden source | DVE field | Notes |
|------------------|-----------|-------|
| `name` | `name` | Required |
| `login.username` | `username` | Login items |
| `login.password` | `password` | Login items |
| `login.uris[0].uri` or `login.uri` | `url` | Primary URI |
| `notes` | `notes` | Item notes |
| `folder` | `folder` | Folder name |
| `favorite` | `tags` | `favorite` when true |
| `login.totp` | `totp_secret` | Validated during import |
| `fields[]` | `custom_fields` | Name/value/type preserved |
| `type` | `credential_type` | See mapping table above |

## Known limitations and quirks

- **Encrypted JSON exports** cannot be parsed — export unencrypted JSON only.
- **Collections and group permissions** are not exported — recreate in DVE.
- **Attachments** are not included in standard vault export.
- **Multiple URIs** — DVE uses the first URI; add alternates manually if needed.

## Import into DVE

1. Open **Import** in DVE.
2. Choose **Bitwarden JSON** or **Bitwarden CSV** to match your file.
3. Upload and start the import job.
4. Review warnings for malformed custom fields or TOTP issues.

## Post-import verification checklist

- [ ] Login, secure note, card, and identity counts look reasonable.
- [ ] Custom fields visible on items that had Bitwarden `fields`.
- [ ] Favorites imported with `favorite` tag.
- [ ] Spot-check org-shared credentials if applicable.
- [ ] Delete JSON/CSV export files securely.
- [ ] Disable Bitwarden browser extension auto-fill after cutover.

## Related guides

- [Migration Overview](overview.md)
- [Dashlane Migration Guide](dashlane.md)
- [Generic CSV Migration Guide](generic-csv.md)