Vault sources · Genosyn Docs

Why connect one

Credentials maintained in two places drift. Someone rotates a password in Bitwarden and the copy in Genosyn quietly becomes wrong, or a new hire is given a login that Genosyn has never heard of. A Vault source removes the second copy: Genosyn learns which items exist and what they are called, so a Member can share one and an AI Employee can be granted one, and every secret is still read from Bitwarden at the moment it is used.

Connect a Vault source

Only company owners and admins can do this, and only they can see the source afterwards. A source holds the master password to an entire external vault, which is a bigger thing to hold than any single Vault item.

1. Open Vault from the company navigation, choose Integrations in the sidebar, and pick Bitwarden under Available integrations. The same card covers Vaultwarden — the two speak one protocol, and the Server URL below is what tells them apart.
2. Label — what you would call it out loud, such as Bitwarden — Engineering. Every item that comes across is shown as mirrored from this label.
3. Server URL — https://vault.bitwarden.com,https://vault.bitwarden.eu, or the web vault URL of your own install. See self-hosted Vaultwarden below.
4. Email and Master password — the Bitwarden sign-in whose vault should be mirrored. Prefer a sign-in that already sees exactly what Genosyn should see over a personal one.
5. Client id and Client secret — optional, and the recommended way to connect. This is the Bitwarden API key; supply both or neither. See two-step login.
6. Folder or collection — optional. Leave it blank to mirror everything the sign-in can read, or name one folder or collection to mirror only the items filed there. The name is matched exactly, ignoring case.
7. Default visibility — Restricted, the default, or Company-wide. It applies to items as they arrive; you can change any of them afterwards.
8. Choose Connect Vault source. Genosyn proves the sign-in, and then runs the first sync straight away — there is no separate step to bring the items in. The new source appears in the list with the number of items it mirrors and when it last synced. Sync now repeats that sync whenever you want it. If the sign-in worked but the first sync did not, the source is still connected and its row says what went wrong.

What crosses over

Bitwarden Logins and Secure notes, and nothing else. Cards, identities, SSH keys and the newer record types are skipped, as is anything in the trash and anything outside the folder or collection scope. Each sync reports what it added, updated, removed, and skipped, and by which reason.

• A mirrored login carries its title, username, and website. Its password is not copied — see what Genosyn stores.
• If the Bitwarden item carries an authenticator seed, the mirror is shown as having authenticator codes and the current code is generated live. A seed Genosyn cannot parse costs the item its codes, not its password.
• Bitwarden passkeys are not mirrored. A mirrored login shows no software passkeys, and one cannot be created on it.
• Item notes stay in Bitwarden. A mirrored login's Private context in Genosyn is empty. A secure note is different: its body is the secret, so it is fetched live when someone reveals it.

What Genosyn stores, and what it does not

Mirrored: The item's title, username, website, and type, plus the Bitwarden item id and revision. That is what the Vault needs in order to list it, search it, share it, and Grant it — and it is enough for all of that to keep working while Bitwarden is unreachable.

Not stored: The password. It is fetched from Bitwarden at the moment it is revealed, copied, or typed into a sign-in form in the Browser by an AI Employee, and it is not written into Genosyn on the way past. The same is true of a secure note's body and of an authenticator seed.

Kept encrypted: The sign-in material on the source itself: the email, the master password, and the API key if you supplied one. Encrypted with the instance encryption key, on the same company-scoped key ring as every other Genosyn secret, and never returned by any API.

Read-only, and how changes arrive

Genosyn never writes to Bitwarden. Editing, rotating, and deleting all happen there; attempting to change a mirrored item's contents or authenticator in Genosyn is refused with a message pointing back at the external vault, and Delete is not offered on a mirror at all. A mirror is a reference, not a copy — a write here would either be undone by the next sync or, worse, look like a rotation that never reached the system of record.

Genosyn syncs every source every 15 minutes, and Sync now does it immediately. Lag matters less than it sounds: because a password is resolved live at the moment of use, a rotation in Bitwarden is picked up on the very next use. What the sync is actually for is new items appearing, renames landing, and deleted items going away.

Access and Grants

Member Access and AI Employee Grants on a mirrored item work exactly as they do on a native one, and they are Genosyn's own. They are not read from Bitwarden: a Bitwarden collection does not become an Access list, and membership of the Bitwarden organization confers nothing here. New mirrors start at the source's Default visibility, and you set Member access and Grants per item from there.

Company owners and admins keep full sharing and visibility control over a mirror; only editing and deleting are off. An AI Employee with a Use Grant signs in with a mirrored login through browser_fill_vault just as it would with a native one, and the password still never enters model context.

Two-step login, and why an API key is better

Use a Bitwarden API key. In Bitwarden, open Settings → Security → Keys and choose View API key, then paste the client id and client secret into the Vault source. An API-key sign-in skips two-step login and Bitwarden's new-device verification, which is what makes it the right choice here: Genosyn re-authenticates on its own schedule, with nobody sitting in front of an authenticator app.

Without an API key, enter a current one-time authenticator code when you connect. That succeeds only on a server that supports remembering the device; where it does not, the first sign-in works and later unattended syncs start failing, and the source's status will say so.

Self-hosted Vaultwarden

Give the web vault URL and nothing more — https://vault.example.com. Genosyn derives the identity and api paths itself, so do not append /identity or /api. A bare hostname is treated as https; the URL must not embed credentials, a query, or a fragment. The bitwarden.com and bitwarden.eu hosts are recognized and mapped to their own identity and api hosts automatically.

If the server sits on a private address, allow it first. Genosyn refuses outbound requests that resolve to a private, loopback, or link-local address — the same check every other outbound surface uses, so that a company admin cannot aim Genosyn at the network the host itself is on. A Vaultwarden behind a public HTTPS name needs nothing. One on 192.168.x.x, 10.x.x.x, or a private DNS name needs its hostname added to security.outboundPrivateHostAllowlist in the instance configuration, after which it connects normally. Until it is added, connecting reports that the host resolves to a private address and names the setting.

Disconnecting

Removing a Vault source removes every item mirrored from it, together with the Member Access and AI Employee Grants attached to those items; Genosyn reports how many items went. Nothing in Bitwarden changes and nothing is lost, because the mirrors held no secrets. Access and Grants go because they are meaningless without the items — and because leaving them behind would silently re-grant everyone the moment you reconnected. Reconnecting mirrors the items as new, and you set Access and Grants again.

Troubleshooting

A source that fails keeps its reason on its own row, so a sync that broke overnight is readable in the morning without reproducing it.

• Two-step login: "This Bitwarden account requires two-step login." Enter a current authenticator code, or — better — connect with a Bitwarden API key instead.
• New device: "Bitwarden wants to verify this as a new device." Bitwarden emailed a code to the mailbox and is waiting for it. An API-key sign-in is exempt from this check; switch to one rather than trying to satisfy it.
• Did not unlock: "That master password did not unlock the Bitwarden vault." The sign-in itself worked, so the email and any API key are fine and the master password is not. It usually means it was changed in Bitwarden; update it on the Vault source.
• No master-password unlock: "This Bitwarden account has no master-password unlock." Single sign-on and key-connector accounts derive their key elsewhere, and Genosyn cannot read them at all. Connect a sign-in that unlocks with a master password.
• Unreachable: "The Bitwarden server at … could not be reached." Check the URL, and on a shared multi-tenant install check that the address is a public one.

Advanced

Vault sources live inside the Vault API at /api/companies/:companyId/vault/sources, and every route there is gated to company owners and admins on top of the Vault surface's own guards — no AI Browser session, no API key, no caching. Alongside the usual list, create, update, and delete, a source can be synced on demand (POST …/sources/:sourceId/sync); creating one syncs it once straight away. Errors come back as { error } carrying the same wording the UI shows.

The 15-minute sweep is a poll, because Bitwarden offers no change feed. One process holds the scheduler lease at a time, so running several replicas does not multiply the load on an operator's Vaultwarden, and a source that fails is left alone until the next pass. Connecting, updating, disconnecting, and syncing a source are audited under Settings → Audit log, with no credential in the event.