Vaultwarden CLI & API Documentation#

Instance: https://vaultwarden.roomit.xyz/
Last Updated: November 2024

Table of Contents#

  1. Setup & Login
  2. Vault Management API (bw serve)
  3. Direct Vaultwarden API
  4. Create Items
  5. Read Items
  6. Update & Delete Items
  7. Troubleshooting
  8. Cheat Sheet

1. Setup & Login#

Konfigurasi Server#

bw config server https://vaultwarden.roomit.xyz/

Login dengan API Key#

bw login dwiyan.wijatmiko@roomit.com --apikey

Note: Login via email/password tidak bisa jika SSO required. Gunakan API Key dari web vault:
Web Vault → Settings → Security → Keys → API Key

Unlock Vault#

# Unlock dan simpan session key
export BW_SESSION=$(bw unlock --raw)

# Atau manual
bw unlock

Sync Vault#

bw sync

Cek Status#

bw status

2. Vault Management API (bw serve)#

Start API Server#

# Default localhost:8087
bw serve

# Custom host/port
bw serve --hostname 0.0.0.0 --port 8087

Cek Port (macOS)#

sudo lsof -i :8087

Cek Port (Linux)#

ss -tulpn | grep 8087

Unlock via API#

curl -X POST http://localhost:8087/unlock \
  -H "Content-Type: application/json" \
  -d '{"password": "YOUR_MASTER_PASSWORD"}'

Lock via API#

curl -X POST http://localhost:8087/lock

Sync via API#

curl -X POST http://localhost:8087/sync

Status via API#

curl http://localhost:8087/status

3. Direct Vaultwarden API#

Get Access Token#

curl -X POST https://vaultwarden.roomit.xyz/identity/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=api&client_id=user.YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGc...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Note: Token expired setelah 3600 detik (1 jam). Simpan token ke variable:

TOKEN=$(curl -s -X POST https://vaultwarden.roomit.xyz/identity/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=api&client_id=user.CLIENT_ID&client_secret=CLIENT_SECRET" \
  | jq -r '.access_token')

Sync Vault (Get All Items)#

curl -X GET https://vaultwarden.roomit.xyz/api/sync \
  -H "Authorization: Bearer $TOKEN"

4. Create Items#

echo '{"type":1,"name":"Gmail Account","login":{"username":"user@example.com","password":"MyPass123","uris":[{"uri":"https://gmail.com"}]}}' | bw create item

Cara 2: Heredoc#

cat <<'EOF' | bw create item
{
  "type": 1,
  "name": "Gmail Account",
  "login": {
    "username": "user@example.com",
    "password": "MyPass123",
    "uris": [
      { "uri": "https://gmail.com" }
    ]
  },
  "notes": "Catatan tambahan (opsional)"
}
EOF

Cara 3: Dari File#

# Buat file JSON
cat > item.json << 'EOF'
{
  "type": 1,
  "name": "Gmail Account",
  "login": {
    "username": "user@example.com",
    "password": "MyPass123",
    "uris": [{ "uri": "https://gmail.com" }]
  }
}
EOF

# Create item
cat item.json | bw create item

Cara 4: Base64 Encoded#

# Encode JSON
ENCODED=$(echo '{"type":1,"name":"Gmail Account","login":{"username":"user@example.com","password":"MyPass123"}}' | base64 -w 0)

# Create item
bw create item $ENCODED

Cara 5: Via Vault Management API#

curl -X POST http://localhost:8087/object/item \
  -H "Content-Type: application/json" \
  -d '{
    "type": 1,
    "name": "Gmail Account",
    "login": {
      "username": "user@example.com",
      "password": "MyPass123",
      "uris": [{ "uri": "https://gmail.com" }]
    }
  }'

Cara 6: Direct Vaultwarden API#

curl -X POST https://vaultwarden.roomit.xyz/api/ciphers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": 1,
    "name": "Gmail Account",
    "login": {
      "username": "user@example.com",
      "password": "MyPass123",
      "uris": [{ "uri": "https://gmail.com" }]
    }
  }'

Item Types#

TypeValueKeterangan
Login1Username & password
Secure Note2Catatan terenkripsi
Card3Kartu kredit/debit
Identity4Data identitas

Template per Item Type#

Login Item#

{
  "type": 1,
  "name": "Website Name",
  "notes": "Optional notes",
  "favorite": false,
  "folderId": null,
  "login": {
    "username": "your_username",
    "password": "your_password",
    "totp": null,
    "uris": [
      { "match": null, "uri": "https://example.com" }
    ]
  }
}

Secure Note#

{
  "type": 2,
  "name": "Note Name",
  "notes": "Secret information here",
  "secureNote": {
    "type": 0
  }
}

Card#

{
  "type": 3,
  "name": "Credit Card",
  "card": {
    "cardholderName": "Dwiyan Wijatmiko",
    "brand": "Visa",
    "number": "4111111111111111",
    "expMonth": "12",
    "expYear": "2025",
    "code": "123"
  }
}

Identity#

{
  "type": 4,
  "name": "Identity Name",
  "identity": {
    "title": "Mr",
    "firstName": "Dwiyan",
    "lastName": "Wijatmiko",
    "email": "dwiyan@example.com",
    "phone": "+6281234567890",
    "company": "PT roomit Sekuritas Indonesia"
  }
}

5. Read Items#

List All Items#

# Via CLI
bw list items

# Via API
curl http://localhost:8087/list/object/items

Search Item#

# Via CLI
bw list items --search "gmail"

# Via API
curl "http://localhost:8087/list/object/items?search=gmail"

Get Item by ID#

# Via CLI
bw get item ITEM_ID

# Via API
curl http://localhost:8087/object/item/ITEM_ID

List Folders#

# Via CLI
bw list folders

# Via API
curl http://localhost:8087/list/object/folders

List Collections#

# Via CLI
bw list collections

# Via API
curl http://localhost:8087/list/object/collections

Generate Password#

# Via CLI
bw generate -uln --length 20

# Via API
curl "http://localhost:8087/generate?length=20&uppercase=true&lowercase=true&number=true&special=true"

6. Update & Delete Items#

Update Item#

# Via CLI
bw get item ITEM_ID | jq '.login.password = "NewPassword"' | bw edit item ITEM_ID

# Via API
curl -X PUT http://localhost:8087/object/item/ITEM_ID \
  -H "Content-Type: application/json" \
  -d '{
    "type": 1,
    "name": "Updated Name",
    "login": {
      "username": "user@example.com",
      "password": "NewPassword123"
    }
  }'

Delete Item#

# Via CLI
bw delete item ITEM_ID

# Via API
curl -X DELETE http://localhost:8087/object/item/ITEM_ID

Create Folder#

# Via CLI
echo '{"name":"Work Accounts"}' | bw create folder

# Via API
curl -X POST http://localhost:8087/object/folder \
  -H "Content-Type: application/json" \
  -d '{"name": "Work Accounts"}'

7. Troubleshooting#

Error: SSO sign-in is required#

# Gunakan API Key login
bw login dwiyan.wijatmiko@roomit.com --apikey

Error: requestJson was not provided#

# Salah ❌
bw create item

# Benar ✅ - JSON harus di-pipe atau di-encode base64
echo '{"type":1,"name":"Test","login":{"username":"u","password":"p"}}' | bw create item

Error: Error parsing the encoded request data#

# Hindari single quote langsung di shell, gunakan heredoc atau file
cat <<'EOF' | bw create item
{"type":1,"name":"Test Item","login":{"username":"user","password":"pass"}}
EOF

Vault Locked#

# Unlock vault
bw unlock

# Atau via API
curl -X POST http://localhost:8087/unlock \
  -H "Content-Type: application/json" \
  -d '{"password": "MASTER_PASSWORD"}'

Port 8087 Sudah Dipakai#

# Cek proses yang pakai port 8087
sudo lsof -i :8087        # macOS
ss -tulpn | grep 8087     # Linux

# Kill proses
kill -9 $(lsof -ti:8087)

# Atau ganti port
bw serve --port 8088

Token Expired (Direct API)#

# Re-generate token
TOKEN=$(curl -s -X POST https://vaultwarden.roomit.xyz/identity/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=api&client_id=user.CLIENT_ID&client_secret=CLIENT_SECRET" \
  | jq -r '.access_token')

8. Cheat Sheet#

CLI Commands#

CommandKeterangan
bw config server <url>Set Vaultwarden server
bw login --apikeyLogin dengan API Key
bw unlockUnlock vault
bw lockLock vault
bw syncSync vault
bw statusCek status vault
bw list itemsList semua item
bw list items --search <keyword>Search item
bw get item <id>Get item by ID
bw create itemCreate item (pipe JSON)
bw edit item <id>Update item
bw delete item <id>Delete item
bw generate -uln --length 20Generate password
bw serve --port 8087Start API server

Vault Management API Endpoints#

MethodEndpointKeterangan
GET/statusStatus vault
POST/unlockUnlock vault
POST/lockLock vault
POST/syncSync vault
GET/list/object/itemsList semua item
GET/list/object/foldersList folders
GET/list/object/collectionsList collections
GET/object/item/:idGet item by ID
POST/object/itemCreate item
PUT/object/item/:idUpdate item
DELETE/object/item/:idDelete item
GET/generateGenerate password

Environment Variables#

export BW_CLIENTID="user.YOUR_CLIENT_ID"
export BW_CLIENTSECRET="YOUR_CLIENT_SECRET"
export BW_PASSWORD="YOUR_MASTER_PASSWORD"
export BW_SESSION=$(bw unlock --raw)
Backward Konfigurasi GNU-PGP (GPG) Enkripsi untuk Sat-Master Btrfs Concept Forward