Organization Groups API

Manage user groups for simplified permission management

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

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

Feature	Groups	Direct Assignment
Scalability	High - add many users at once	Low - one user at a time
Maintenance	Easy - update group membership	Difficult - update each user
Audit Trail	Clear group structure	Hard to track
Directory Sync	Supported	Not applicable
Flexibility	Moderate	High

Recommendation: Use groups for most use cases. Reserve direct user assignment for exceptional cases.