Skip to main content

​
Overview

Groups simplify permission management by allowing you to assign collections and permissions to groups of users rather than individual users.
Groups are only available on Teams and Enterprise plans.

​
Get Group

Retrieve a specific group. 
GET /organizations/{orgId}/groups/{id}
​
orgId
string
required
Organization ID
​
id
string
required
Group ID

​
Response

​
id
string
required
Group unique identifier
​
organizationId
string
required
Parent organization ID
​
name
string
required
Group name
​
accessAll
boolean
required
Whether group has access to all collections
​
externalId
string
External identifier for directory sync

​
Get Group with Details

Retrieve group including collection assignments. 
GET /organizations/{orgId}/groups/{id}/details
​
orgId
string
required
Organization ID
​
id
string
required
Group ID

​
Response

Includes all group data plus:
​
collections
array
Array of collection access assignments

​
List Groups

Retrieve all groups in an organization. 
GET /organizations/{orgId}/groups
​
orgId
string
required
Organization ID

​
List Groups with Details

Retrieve all groups including collection assignments. 
GET /organizations/{orgId}/groups/details
​
orgId
string
required
Organization ID

​
Get Group Users

Retrieve all user IDs in a group. 
GET /organizations/{orgId}/groups/{id}/users
​
orgId
string
required
Organization ID
​
id
string
required
Group ID

​
Response

Returns an array of organization user IDs.

​
Create Group

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

​
Request Body

​
name
string
required
Group name
​
accessAll
boolean
default:"false"
Grant access to all collections
​
externalId
string
External identifier for directory sync
​
collections
array
Collection access assignments (required if accessAll=false)
​
users
array
Array of organization user IDs to add to group

​
Collection Access Object

​
id
string
required
Collection ID
​
readOnly
boolean
default:"false"
Read-only access
​
hidePasswords
boolean
default:"false"
Hide password fields

​
Update Group

Update an existing group. 
PUT /organizations/{orgId}/groups/{id}
​
orgId
string
required
Organization ID
​
id
string
required
Group ID

​
Request Body

Same as Create Group - all fields must be provided.
You cannot add yourself to a group unless admin access to all collections is enabled.

​
Delete Group

Permanently delete a group. 
DELETE /organizations/{orgId}/groups/{id}
​
orgId
string
required
Organization ID
​
id
string
required
Group ID
Deleting a group removes users from the group but does not delete the users themselves. Users lose access to collections granted via the group.

​
Bulk Delete Groups

Delete multiple groups at once. 
DELETE /organizations/{orgId}/groups
​
orgId
string
required
Organization ID
​
ids
array
required
Array of group IDs to delete

​
Group Management Best Practices

​
Organizing Groups

  1. By Department: Engineering, Marketing, Sales, Finance
  2. By Role: Admins, Managers, Contractors
  3. By Project: Project Alpha, Beta Testing, Production
  4. By Location: US Team, EU Team, APAC Team

​
Naming Conventions

[Department/Team] - [Access Level]

Examples:
- Engineering - Full Access
- Marketing - Read Only
- Finance - Restricted
- Contractors - Limited

​
Access Strategy

  1. Use groups instead of individual users for collection access
  2. Keep groups focused - one clear purpose per group
  3. Review membership regularly - audit who’s in each group
  4. Use accessAll sparingly - grant specific collection access when possible
  5. Leverage directory sync - automate group membership with LDAP/SCIM

​
Permission Inheritance

Users inherit collection access from all groups they belong to: 
User A belongs to:
- Group 1: Collection A (read-only)
- Group 2: Collection B (read-write)
- Group 3: Collection A (read-write)

Effective permissions:
- Collection A: read-write (highest permission wins)
- Collection B: read-write
When a user is in multiple groups with different permissions to the same collection, they receive the highest level of access.

​
Directory Sync

Groups can be synchronized with external directory services:

​
LDAP/Active Directory

{
  "name": "Engineering",
  "externalId": "CN=Engineering,OU=Groups,DC=company,DC=com",
  "accessAll": false,
  "collections": [...]
}

​
SCIM

Groups created via SCIM automatically include the external ID: 
{
  "name": "Marketing Team",
  "externalId": "00g1234abcd",
  "accessAll": false
}
Do not manually modify groups that are managed by directory sync. Changes may be overwritten during the next sync.

​
Groups vs Direct User Assignment

FeatureGroupsDirect Assignment
ScalabilityHigh - add many users at onceLow - one user at a time
MaintenanceEasy - update group membershipDifficult - update each user
Audit TrailClear group structureHard to track
Directory SyncSupportedNot applicable
FlexibilityModerateHigh
Recommendation: Use groups for most use cases. Reserve direct user assignment for exceptional cases.

Build docs developers (and LLMs) love

Get started for freeTalk to us