Folders

Folders for organizing secrets with per-recipient access control and encryption keys.

Service: passwords.folders

Folders for organizing secrets. A secret can belong to at most one folder (folder_id). Folders appear in the sidebar with a name, color, and icon.

Fields

Field	Type	Required	Description
id	string	—	Primary key. Read-only, auto-generated
position	float		Fractional drag-sort position in the sidebar
enc_name	string	✅	Encrypted folder name. Plain string after decryption
enc_color	string		Encrypted color identifier. Plain string after decryption. Values: primary · secondary · success · danger · warning · info · dark
enc_icon	string		Encrypted icon name. Plain string after decryption. Value is a Bootstrap Icons name (e.g. "folder", "shield-lock")
created_at	string	—	ISO 8601 creation timestamp. Read-only
updated_at	string	—	ISO 8601 last update timestamp. Read-only
folder_user_role	UserRole[]	✅	Access control + encryption keys

UserRole

Access control entry. Each recipient gets their own copy of the record’s encryption key, wrapped with their public key.

Field	Type	Required	Description
user_id	string	✅	Recipient user id
role	string	✅	Role identifier. Values: owner · editor · viewer
wrapped_content_key	string	✅	Record key wrapped for this recipient (base64)

find

List folders accessible to the authenticated user.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "passwords.folders.find",
  "params": {
    "limit": 100,
    "fields": [
      "id", "position",
      "enc_name", "enc_color", "enc_icon",
      "folder_user_role.user_id",
      "folder_user_role.wrapped_content_key"
    ]
  },
  "id": 10
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "items": [
      {
        "id": "1920438291700",
        "position": 1000.0,
        "enc_name": "<base64>",
        "enc_color": "<base64>",
        "enc_icon": "<base64>",
        "folder_user_role": [
          { "user_id": "42", "wrapped_content_key": "<base64>" }
        ]
      }
    ],
    "total": 1
  },
  "id": 10
}

findOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "passwords.folders.findOneById",
  "params": {
    "id": "1920438291700"
  },
  "id": 11
}

create

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "passwords.folders.create",
  "params": {
    "document": {
      "position": 3000.0,
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "enc_icon": "<base64>",
      "folder_user_role": [
        { "user_id": "42", "role": "owner", "wrapped_content_key": "<base64>" }
      ]
    }
  },
  "id": 12
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "id": "1920438291720",
    "enc_name": "<base64>",
    "created_at": "2026-05-13T18:30:00Z"
  },
  "id": 12
}

updateOneById

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "passwords.folders.updateOneById",
  "params": {
    "id": "1920438291700",
    "document": {
      "position": 1500.0,
      "enc_name": "<base64-new>"
    }
  },
  "id": 13
}

replaceOneById

Full replacement — all writable fields must be provided. Unlike updateOneById, omitted fields are reset to defaults. Nested collections (folder_user_role) are not accepted — use updateOneById to modify them.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "passwords.folders.replaceOneById",
  "params": {
    "id": "1920438291700",
    "document": {
      "position": 1500.0,
      "enc_name": "<base64>",
      "enc_color": "<base64>",
      "enc_icon": "<base64>"
    }
  },
  "id": 13
}

deleteOneById

Delete a folder. Secrets that belonged to this folder are moved to unfiled (folder_id becomes null).

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "passwords.folders.deleteOneById",
  "params": {
    "id": "1920438291700"
  },
  "id": 14
}

update

Batch update folders in a single transaction (all-or-nothing). See Batch operations.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "passwords.folders.update",
  "params": {
    "items": [
      { "id": "1920438291700", "document": { "position": 500.0 } },
      { "id": "1920438291705", "document": { "position": 1500.0 } }
    ]
  },
  "id": 15
}

delete

Batch delete folders in a single transaction (all-or-nothing). See Batch operations.

WebSocket

Request

{
  "jsonrpc": "2.0",
  "method": "passwords.folders.delete",
  "params": {
    "items": [
      { "id": "1920438291700" },
      { "id": "1920438291705" }
    ]
  },
  "id": 16
}