SecondBrain/reference/vaultwarden-permission-parity-gotchas.md

type	subtype	title	summary	tags	scope	date	last_updated	last_reviewed	related	source
reference	api-integration	Vaultwarden vs Bitwarden Cloud — permission and feature parity gotchas	Verified differences between self-hosted Vaultwarden and Bitwarden Cloud that break security designs copied from Bitwarden docs — Edit permission includes delete, no deletion-restriction org policy, no Secrets Manager, trash never auto-purges by default — plus org bot-onboarding gotchas (accept ≠ confirm, collection assignment can silently not persist).	type/reference tool/vaultwarden domain/credential-management domain/security	global	2026-07-09	2026-07-10	2026-07-09	credvault-integration-master-plan	ruby-gems

Vaultwarden Parity Gotchas

Bitwarden's official help docs describe Bitwarden Cloud. Vaultwarden reimplements the server and does NOT match on these points (verified 2026-07-09, vaultwarden discussions #6131, issue #6269):

• Edit collection permission includes deleting items. There is NO org setting to restrict item deletion to Manage-permission members (that toggle is Cloud-only). A "bot with Edit but can't delete" design is impossible server-side — enforce in your wrapper/OS layer.
• Manage permission is worse for least-privilege — it grants collection-membership admin.
• Secrets Manager does not exist in Vaultwarden. Don't plan it as a backend.
• Trash never auto-purges by default — permanent deletion only with TRASH_AUTO_DELETE_DAYS set. (Cloud docs say 30 days.) Safer, but don't cite "30-day window".
• Password history ("last 5") is written client-side into the cipher; compatible clients preserve it, raw API writes can clobber it. Likely works — verify per instance.
• bw CLI API-key login still requires bw unlock + master password for vault data; the API key does not replace the master password. Non-interactive automation needs a protected --passwordfile.
• bw list items --search doesn't match custom fields — filter client-side on parsed JSON.
• Maintainer (BlackDex) states Vaultwarden "does not support the full range of RBAC/GBAC/CBAC".

Org member (bot) onboarding gotchas (verified 2026-07-09, credvault Phase 0)

• Accept ≠ confirm. A member who accepts an invite still sees NO organization via bw list organizations until an org admin explicitly clicks Confirm on the member (Members page → three-dot menu). Confirm is the step that grants the org key; editing the member's role/collections is not it.
• Collection assignment can silently fail to persist — after the admin sets a collection in Edit member → Collections, bw list collections (bot side) can still return [] after sync. Verify the collection badge shows on the Members list row; re-open the dialog and re-save if not.
• bw sync -f after any server-side membership change — login/unlock state alone won't refresh org/collection visibility on the client.
• Password history verified working on Vaultwarden: bw edit with a changed login password preserves the old one in passwordHistory with lastUsedDate. Custom fields round-trip intact through bw list items JSON.

Credential rotation gotchas (verified 2026-07-10, credvault e2e)

• Master password rotation invalidates cached bw logins. After changing an account's master password server-side, bw unlock fails (exit 1) even with the correct new --passwordfile — the cached login holds keys derived from the old password. Fix: bw logout, then re-login with the API key, then unlock works.
• bw sessions are per BITWARDENCLI_APPDATA_DIR. A plain bw logout in a shell only clears the default appdata dir; tool-specific dirs (e.g. credvault's ~/.config/credvault/bitwarden) keep their stale session until you log out with the matching env var set.
• API key rotation changes only client_secret — client_id is stable across rotations.
• bw unlock --passwordfile reads only the first line, so a trailing newline from an editor (nvim etc.) is harmless.

bw CLI scripting gotchas (verified 2026-07-10, credvault backup script)

• bw unlock alone does not unlock the vault for subsequent commands — you must capture the session token (BW_SESSION=$(bw unlock --passwordfile f --raw)) and export it. Without it, later bw export/bw list run against a locked vault; with stderr silenced this looks like a hang or a missing-output failure.
• bw config server fails while logged in ("Logout required before server config update"), even when setting the identical URL. Idempotent scripts must compare bw config server (no args prints current) and skip when it matches.
• bw login --apikey errors if already logged in — guard with bw login --check.

Rule of thumb: any "Bitwarden supports X" claim from bitwarden.com/help must be re-verified against the deployed Vaultwarden version before it becomes a security assumption.