Bitwarden MCP Tools & API Patterns
Overview
The Bitwarden plugin gives an MSP the admin view of one client's Bitwarden
organization through the
Bitwarden Public API: who is a
member, their role and 2FA state, which groups and collections exist, which
security policies are on, what happened in the event log, and how many seats
are licensed.
Every tool is a GET. Nothing in this plugin can invite, confirm, revoke,
restore, or remove a member, change a group, collection or policy, or change
seats. Nothing can read vault items or passwords: the Public API does not
expose them. Any remediation you recommend is done by a person in the
Bitwarden Admin Console.
Connection & Authentication
Conduit connects as a Bitwarden organization API key. The connect form
in the Conduit web UI (/connect/bitwarden) has three fields. Conduit stores
them and passes each to the MCP server as a header; nothing is set on the
client, and Conduit drops any X-Bitwarden-* header a client sends:
| Conduit field |
Header |
Notes |
| Organization client_id |
X-Bitwarden-Client-Id |
Starts with organization.. A personal user. key is refused. |
| Organization client_secret |
X-Bitwarden-Client-Secret |
Secret. Redacted from all tool output. |
| Region |
X-Bitwarden-Region |
us (bitwarden.com, the default) or eu (bitwarden.eu). |
Facts that shape every conversation about access:
- Teams or Enterprise only. The Public API does not exist on Free,
Families or Starter plans. A 403 usually means the plan lacks it.
- Owner-only key. Only an organization owner can view or rotate the key
(Admin Console > Settings > Organization info > View API key).
- There is no read-only key. The key's only scope,
api.organization,
is full organization admin. This plugin wraps only read routes, but the
stored key could change the organization if it leaked. Rotate it from the
same Admin Console page if it is ever exposed.
- One connection, one organization. The key belongs to one Bitwarden
organization. Each client organization has its own key; a provider
(reseller) relationship does not give one key access to several clients.
- Self-hosted Bitwarden is not supported. Only US and EU cloud work.
The MCP server exchanges the key for a short-lived bearer token, caches it,
and on a 401 refreshes once and retries. You never handle the token.
The 12 tools
| Tool |
What it returns |
Conduit tier |
bitwarden_members_list |
Every member: role, status, 2FA, email, externalId, collection access |
read |
bitwarden_members_get |
One member by memberId (GUID) |
read |
bitwarden_members_list_group_ids |
Group IDs one member belongs to |
read |
bitwarden_groups_list |
Every group and its collection access |
read |
bitwarden_groups_get |
One group by groupId |
read |
bitwarden_groups_list_member_ids |
Member IDs in one group |
read |
bitwarden_collections_list |
Every collection and its group access (metadata only) |
read |
bitwarden_collections_get |
One collection by collectionId |
read |
bitwarden_policies_list |
Every configured security policy, enabled flag and settings |
read |
bitwarden_policies_get |
One policy by policyType integer (404 if never configured) |
read |
bitwarden_events_list |
The organization audit event log, paged |
admin-gated |
bitwarden_subscription_get |
Password Manager and Secrets Manager seats, autoscale limits, storage |
read |
bitwarden_events_list is admin-gated in Conduit. It needs the admin
tier in the gateway access editor; a user granted only read gets a denial for
it while the other 11 tools work. Event data carries emails, IP addresses
and device details, which is why it sits behind the higher grant. When the
event log is denied, say so and continue with what the read tools show;
do not present an event-free review as complete. Confirm the live grant in
the access editor.
Identifiers and enums
All IDs (memberId, groupId, collectionId, event filters) are GUIDs.
Anything else is refused before a request is made. A member's id (the
organization membership) is not the same as their userId (the Bitwarden
account); event filters such as actingUserId take the userId.
Member type (role):
| Value |
Role |
| 0 |
Owner |
| 1 |
Admin |
| 2 |
User |
| 4 |
Custom |
Member status:
| Value |
Status |
Meaning for an audit |
| -1 |
Revoked |
Still listed, but has no access to organization data |
| 0 |
Invited |
Invite not yet accepted; no Bitwarden account linked yet |
| 1 |
Accepted |
Accepted but not yet confirmed by an admin; cannot decrypt shared items |
| 2 |
Confirmed |
Full member |
| 3 |
Staged |
Created ahead of an invite; not active yet |
Policy types are integers 0 to 23; the policyType parameter of
bitwarden_policies_get lists them all. See
security-posture for the ones that matter in
a review.
Pagination
- Members, groups, collections and policies come back whole. The
response is
{object: "list", data: [...], continuationToken: null}. The
API does not page these lists, so one call is the full set.
- The event log is paged.
bitwarden_events_list returns a
continuationToken. Pass it back unchanged to get the next page, and stop
when it is null. The tool never pages on its own.
- Event ranges. With no
start/end the log covers the last 30 days.
Bitwarden rejects ranges over 367 days. Dates are ISO 8601
(2026-10-01 or 2026-10-01T00:00:00Z).
- One event filter at a time. Pass at most one of
actingUserId,
itemId, secretId, projectId. Bitwarden would silently ignore the
others, so the tool refuses the combination.
Truncated responses
Tool output is capped (about 60,000 characters). A list that does not fit is
cut structurally and marked:
{
"object": "list",
"continuationToken": null,
"truncated": true,
"returned_items": 180,
"total_items_in_page": 412,
"truncation_hint": "...",
"data": [ ... ]
}
Always check for truncated: true before counting anything.
- On a full list (members, groups, collections) there is no next page,
so the missing items cannot be fetched by paging. Report the count as
partial ("first 180 of 412 members"), then work per record:
bitwarden_groups_list and bitwarden_groups_list_member_ids give member
IDs, and bitwarden_members_get returns one member. Members in no group
cannot be reached that way; say so.
- On an event page, following
continuationToken skips the items that
were dropped. Re-run with a shorter start/end window instead.
Error Handling
Errors come back as tool errors (isError: true) carrying the HTTP status,
a hint, Bitwarden's message and field errors, and a request_id when
Bitwarden sent one.
| Status |
Meaning |
Action |
| 400 |
Invalid request (often a bad date range or parameter) |
Read the field errors; check the event range is under 367 days |
| 401 |
Key rejected even after a token refresh |
The key was probably rotated. An owner re-submits the Conduit connect form with the new client_secret |
| 403 |
Key lacks access |
The organization is not on Teams or Enterprise, or the region is wrong |
| 404 |
Not found |
Wrong GUID, or for bitwarden_policies_get, a policy that was never configured (treat as "off") |
| 429 |
Rate limited |
Wait for the Retry after Ns value in the error, then retry once |
| Argument error |
A non-GUID ID, bad date, or two exclusive filters |
Fix the argument; no request was sent |
A Conduit denial (the tool is outside your grant) is not a Bitwarden error.
For bitwarden_events_list it means the admin tier is not granted.
Rate limits
Bitwarden does not publish fixed Public API limits. Keep calls sequential,
prefer one list call over many _get calls, and back off on 429 using the
Retry-After value the error reports. Large event sweeps are the usual
cause; narrow the date range rather than paging through a year of events.
Related Skills
1---2name: bitwarden-api-patterns3description: >4 Bitwarden MCP fundamentals: the organization API key passed through Conduit5 as X-Bitwarden-Client-Id / X-Bitwarden-Client-Secret / X-Bitwarden-Region,6 the 12 read-only tools and which one is admin-gated, full-list responses7 versus the paged event log, response truncation, the member role and status8 enums, error and rate-limit handling, and what the Public API can never9 return. Every other Bitwarden skill assumes these patterns.10when_to_use: >-11 When connecting to or calling Bitwarden through the MCP tools, or diagnosing12 a failed Bitwarden request. Use when: bitwarden api, bitwarden connection,13 bitwarden organization api key, bitwarden region, bitwarden 401, bitwarden14 429, bitwarden pagination, continuationToken, or a truncated bitwarden15 response.16metadata:17 source: https://skillmd.com/skills/wyre-ai/bitwarden-api-patterns18---1920# Bitwarden MCP Tools & API Patterns2122## Overview2324The Bitwarden plugin gives an MSP the admin view of one client's Bitwarden25organization through the26[Bitwarden Public API](https://bitwarden.com/help/public-api/): who is a27member, their role and 2FA state, which groups and collections exist, which28security policies are on, what happened in the event log, and how many seats29are licensed.3031Every tool is a `GET`. Nothing in this plugin can invite, confirm, revoke,32restore, or remove a member, change a group, collection or policy, or change33seats. Nothing can read vault items or passwords: the Public API does not34expose them. Any remediation you recommend is done by a person in the35Bitwarden Admin Console.3637## Connection & Authentication3839Conduit connects as a Bitwarden **organization API key**. The connect form40in the Conduit web UI (`/connect/bitwarden`) has three fields. Conduit stores41them and passes each to the MCP server as a header; nothing is set on the42client, and Conduit drops any `X-Bitwarden-*` header a client sends:4344| Conduit field | Header | Notes |45|---|---|---|46| Organization client_id | `X-Bitwarden-Client-Id` | Starts with `organization.`. A personal `user.` key is refused. |47| Organization client_secret | `X-Bitwarden-Client-Secret` | Secret. Redacted from all tool output. |48| Region | `X-Bitwarden-Region` | `us` (bitwarden.com, the default) or `eu` (bitwarden.eu). |4950Facts that shape every conversation about access:5152- **Teams or Enterprise only.** The Public API does not exist on Free,53 Families or Starter plans. A 403 usually means the plan lacks it.54- **Owner-only key.** Only an organization owner can view or rotate the key55 (Admin Console > Settings > Organization info > View API key).56- **There is no read-only key.** The key's only scope, `api.organization`,57 is full organization admin. This plugin wraps only read routes, but the58 stored key could change the organization if it leaked. Rotate it from the59 same Admin Console page if it is ever exposed.60- **One connection, one organization.** The key belongs to one Bitwarden61 organization. Each client organization has its own key; a provider62 (reseller) relationship does not give one key access to several clients.63- **Self-hosted Bitwarden is not supported.** Only US and EU cloud work.6465The MCP server exchanges the key for a short-lived bearer token, caches it,66and on a 401 refreshes once and retries. You never handle the token.6768## The 12 tools6970| Tool | What it returns | Conduit tier |71|---|---|---|72| `bitwarden_members_list` | Every member: role, status, 2FA, email, externalId, collection access | read |73| `bitwarden_members_get` | One member by `memberId` (GUID) | read |74| `bitwarden_members_list_group_ids` | Group IDs one member belongs to | read |75| `bitwarden_groups_list` | Every group and its collection access | read |76| `bitwarden_groups_get` | One group by `groupId` | read |77| `bitwarden_groups_list_member_ids` | Member IDs in one group | read |78| `bitwarden_collections_list` | Every collection and its group access (metadata only) | read |79| `bitwarden_collections_get` | One collection by `collectionId` | read |80| `bitwarden_policies_list` | Every configured security policy, enabled flag and settings | read |81| `bitwarden_policies_get` | One policy by `policyType` integer (404 if never configured) | read |82| `bitwarden_events_list` | The organization audit event log, paged | **admin-gated** |83| `bitwarden_subscription_get` | Password Manager and Secrets Manager seats, autoscale limits, storage | read |8485**`bitwarden_events_list` is admin-gated in Conduit.** It needs the admin86tier in the gateway access editor; a user granted only read gets a denial for87it while the other 11 tools work. Event data carries emails, IP addresses88and device details, which is why it sits behind the higher grant. When the89event log is denied, say so and continue with what the read tools show;90do not present an event-free review as complete. Confirm the live grant in91the access editor.9293## Identifiers and enums9495All IDs (`memberId`, `groupId`, `collectionId`, event filters) are GUIDs.96Anything else is refused before a request is made. A member's `id` (the97organization membership) is not the same as their `userId` (the Bitwarden98account); event filters such as `actingUserId` take the **userId**.99100Member `type` (role):101102| Value | Role |103|---|---|104| 0 | Owner |105| 1 | Admin |106| 2 | User |107| 4 | Custom |108109Member `status`:110111| Value | Status | Meaning for an audit |112|---|---|---|113| -1 | Revoked | Still listed, but has no access to organization data |114| 0 | Invited | Invite not yet accepted; no Bitwarden account linked yet |115| 1 | Accepted | Accepted but not yet confirmed by an admin; cannot decrypt shared items |116| 2 | Confirmed | Full member |117| 3 | Staged | Created ahead of an invite; not active yet |118119Policy types are integers 0 to 23; the `policyType` parameter of120`bitwarden_policies_get` lists them all. See121[security-posture](../security-posture/SKILL.md) for the ones that matter in122a review.123124## Pagination125126- **Members, groups, collections and policies come back whole.** The127 response is `{object: "list", data: [...], continuationToken: null}`. The128 API does not page these lists, so one call is the full set.129- **The event log is paged.** `bitwarden_events_list` returns a130 `continuationToken`. Pass it back unchanged to get the next page, and stop131 when it is `null`. The tool never pages on its own.132- **Event ranges.** With no `start`/`end` the log covers the last 30 days.133 Bitwarden rejects ranges over 367 days. Dates are ISO 8601134 (`2026-10-01` or `2026-10-01T00:00:00Z`).135- **One event filter at a time.** Pass at most one of `actingUserId`,136 `itemId`, `secretId`, `projectId`. Bitwarden would silently ignore the137 others, so the tool refuses the combination.138139## Truncated responses140141Tool output is capped (about 60,000 characters). A list that does not fit is142cut structurally and marked:143144```json145{146 "object": "list",147 "continuationToken": null,148 "truncated": true,149 "returned_items": 180,150 "total_items_in_page": 412,151 "truncation_hint": "...",152 "data": [ ... ]153}154```155156Always check for `truncated: true` before counting anything.157158- On a **full list** (members, groups, collections) there is no next page,159 so the missing items cannot be fetched by paging. Report the count as160 partial ("first 180 of 412 members"), then work per record:161 `bitwarden_groups_list` and `bitwarden_groups_list_member_ids` give member162 IDs, and `bitwarden_members_get` returns one member. Members in no group163 cannot be reached that way; say so.164- On an **event page**, following `continuationToken` skips the items that165 were dropped. Re-run with a shorter `start`/`end` window instead.166167## Error Handling168169Errors come back as tool errors (`isError: true`) carrying the HTTP status,170a hint, Bitwarden's `message` and field `errors`, and a `request_id` when171Bitwarden sent one.172173| Status | Meaning | Action |174|---|---|---|175| 400 | Invalid request (often a bad date range or parameter) | Read the field errors; check the event range is under 367 days |176| 401 | Key rejected even after a token refresh | The key was probably rotated. An owner re-submits the Conduit connect form with the new client_secret |177| 403 | Key lacks access | The organization is not on Teams or Enterprise, or the region is wrong |178| 404 | Not found | Wrong GUID, or for `bitwarden_policies_get`, a policy that was never configured (treat as "off") |179| 429 | Rate limited | Wait for the `Retry after Ns` value in the error, then retry once |180| Argument error | A non-GUID ID, bad date, or two exclusive filters | Fix the argument; no request was sent |181182A Conduit denial (the tool is outside your grant) is not a Bitwarden error.183For `bitwarden_events_list` it means the admin tier is not granted.184185## Rate limits186187Bitwarden does not publish fixed Public API limits. Keep calls sequential,188prefer one list call over many `_get` calls, and back off on 429 using the189`Retry-After` value the error reports. Large event sweeps are the usual190cause; narrow the date range rather than paging through a year of events.191192## Related Skills193194- [security-posture](../security-posture/SKILL.md) - policies, 2FA coverage and admin sprawl195- [offboarding-access-review](../offboarding-access-review/SKILL.md) - what a departing user could reach196- [license-reconciliation](../license-reconciliation/SKILL.md) - seats versus real members197- [event-log-review](../event-log-review/SKILL.md) - reading the admin-gated event log