Skip to main content

​
Overview

Folders help organize personal vault items. They are user-specific and not shared across organizations.
Folders are only available for personal vault items, not organization items.

​
Get Folder

Retrieve a specific folder by ID. 
GET /folders/{id}
​
id
string
required
The folder ID

​
Response

​
id
string
required
Folder unique identifier
​
name
string
required
Encrypted folder name
​
revisionDate
string
required
Last modification timestamp

​
List All Folders

Retrieve all folders for the authenticated user. 
GET /folders

​
Response

Returns a list of all folders belonging to the user. 
curl -X GET "https://api.bitwarden.com/folders" \
  -H "Authorization: Bearer {access_token}"

​
Create Folder

Create a new folder. 
curl -X POST "https://api.bitwarden.com/folders" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2.encrypted_folder_name"
  }'

​
Request Body

​
name
string
required
Encrypted folder name

​
Response

Returns the created folder object with its generated ID.

​
Update Folder

Update an existing folder’s name. 
PUT /folders/{id}
​
id
string
required
The folder ID to update

​
Request Body

​
name
string
required
New encrypted folder name
curl -X PUT "https://api.bitwarden.com/folders/{id}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2.new_encrypted_name"
  }'

​
Delete Folder

Delete a folder permanently. 
DELETE /folders/{id}
​
id
string
required
The folder ID to delete
curl -X DELETE "https://api.bitwarden.com/folders/{id}" \
  -H "Authorization: Bearer {access_token}"
Deleting a folder does not delete the items in it. Items will be moved to “No Folder”.

​
Delete All Folders

Delete all folders for the authenticated user. 
DELETE /folders/all
This will delete all your folders. Items in folders will be moved to “No Folder”. This action cannot be undone.

​
Folder Organization

​
Best Practices

  1. Use Descriptive Names: Name folders clearly to easily find items
  2. Don’t Nest: Folders are flat - use naming conventions like “Work - Email” for logical grouping
  3. Limit Count: Too many folders can make organization difficult
  4. Use Collections Instead: For shared items, use organization collections

​
Folders vs Collections

FeatureFoldersCollections
ScopePersonal items onlyOrganization items
SharingNot sharedShared with groups/users
PermissionsUser has full controlRole-based access
VisibilityUser onlyOrganization members

​
Encryption

Folder names are encrypted client-side before being sent to the server.
The name field must be encrypted using the user’s encryption key. The format is: 
{encType}.{encryptedData}|{iv}|{mac}
Example: 
2.abc123def456|789ghi012|345jkl678

​
Moving Items to Folders

To move items into folders, use the Ciphers API: 
PUT /ciphers/{cipherId}/partial
With body: 
{
  "folderId": "folder-guid-here"
}
See Ciphers API for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us