Folders API

Organize vault items with folders

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

curl -X GET "https://api.bitwarden.com/folders" \
  -H "Authorization: Bearer {access_token}"

---

Create Folder

Create a new folder.

cURL

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

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

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

Feature	Folders	Collections
Scope	Personal items only	Organization items
Sharing	Not shared	Shared with groups/users
Permissions	User has full control	Role-based access
Visibility	User only	Organization 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.