Skip to main content

​
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 -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

PermissionDescription
ViewCan see items in collection
EditCan modify items (requires readOnly: false)
ManageCan edit collection membership
Hide PasswordsCan 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us