Collections API

Organize and share organization vault items with collections

Overview

Collections are used to organize and share vault items within organizations. They enable fine-grained access control by allowing you to:

• Group organization vault items
• Assign access to specific users and groups
• Set read-only or read-write permissions
• Manage which organization members can access which items

Collections are organization-specific. For personal item organization, use Folders.

Get Collection

Retrieve a specific collection by ID.

GET /organizations/{orgId}/collections/{id}

orgId · string · required

Organization ID

id · string · required

Collection ID

Response

id · string · required

Collection unique identifier

organizationId · string · required

Parent organization ID

name · string · required

Encrypted collection name

externalId · string

External identifier for directory sync

---

Get Collection with Details

Retrieve collection with access details (users and groups).

GET /organizations/{orgId}/collections/{id}/details

orgId · string · required

Organization ID

id · string · required

Collection ID

Response

Includes collection data plus:

users · array

Array of user access assignments

groups · array

Array of group access assignments

assigned · boolean

Whether current user has access

readOnly · boolean

Whether current user has read-only access

---

List Collections

Retrieve all collections for an organization.

GET /organizations/{orgId}/collections

orgId · string · required

Organization ID

Response

Returns collections the user has access to manage or read.

---

List Collections with Details

Retrieve all collections with access details.

GET /organizations/{orgId}/collections/details

orgId · string · required

Organization ID

Response

Returns collections with user and group assignments.

---

List User’s Collections

Retrieve all collections assigned to the current user across all organizations.

GET /collections

Response

Returns collections from all organizations where the user is a member.

---

Create Collection

Create a new collection in an organization.

cURL

curl -X POST "https://api.bitwarden.com/organizations/{orgId}/collections" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2.encrypted_collection_name",
    "groups": [
      {
        "id": "group-guid",
        "readOnly": false,
        "hidePasswords": false
      }
    ],
    "users": [
      {
        "id": "user-guid",
        "readOnly": false,
        "hidePasswords": false
      }
    ]
  }'

Request Body

name · string · required

Encrypted collection name

externalId · string

External identifier for sync systems

groups · array

Array of group access assignments

users · array

Array of user access assignments

Group/User Access Object

id · string · required

Group or user ID

readOnly · boolean · default: "false"

Read-only access (cannot edit items)

hidePasswords · boolean · default: "false"

Hide password fields from user

manage · boolean · default: "false"

Can manage collection membership

---

Update Collection

Update an existing collection.

PUT /organizations/{orgId}/collections/{id}

orgId · string · required

Organization ID

id · string · required

Collection ID

Request Body

Same as Create Collection - all fields must be provided.

---

Get Collection Users

Retrieve users assigned to a collection.

GET /organizations/{orgId}/collections/{id}/users

orgId · string · required

Organization ID

id · string · required

Collection ID

Response

Returns array of user access assignments with permissions.

---

Delete Collection

Permanently delete a collection.

DELETE /organizations/{orgId}/collections/{id}

orgId · string · required

Organization ID

id · string · required

Collection ID to delete

Deleting a collection removes all items from that collection. If items are only in this collection, they become unassigned. This action cannot be undone.

---

Bulk Delete Collections

Delete multiple collections at once.

DELETE /organizations/{orgId}/collections

orgId · string · required

Organization ID

ids · array · required

Array of collection IDs to delete

organizationId · string · required

Organization ID (must match path parameter)

---

Bulk Add Collection Access

Add users or groups to multiple collections.

PUT /organizations/{orgId}/collections/bulk-access

orgId · string · required

Organization ID

collectionIds · array · required

Array of collection IDs

users · array

Array of user access assignments

groups · array

Array of group access assignments

---

Collection Permissions

Permission Levels

Permission	Description
View	Can see items in collection
Edit	Can modify items (requires readOnly: false)
Manage	Can edit collection membership
Hide Passwords	Can view items but not passwords

Access Control

Collections support both:

• User-level access: Assign individual users
• Group-level access: Assign groups (all group members inherit access)

Group-based access is recommended for easier management and better security.

---

Best Practices

Organization Strategy

1. Use groups for access control instead of individual users
2. Create collections by department or team for logical organization
3. Limit read-write access - use read-only where possible
4. Review access regularly to ensure proper permissions

Naming Conventions

[Department] - [Team/Purpose]

Examples:
- Engineering - Production Credentials
- Marketing - Social Media Accounts
- Finance - Banking Access

---

Encryption

Collection names are encrypted with the organization key, not individual user keys.

All organization members with access can decrypt collection names using the shared organization key.