127 lines
5.4 KiB
Markdown
127 lines
5.4 KiB
Markdown
# Bitwarden `bw serve` — endpoint cheat sheet
|
|
|
|
Base URL: `http://127.0.0.1:8087` (puerto en `BW_PORT`).
|
|
Todos los endpoints devuelven `{ success: true|false, data?: ..., message?: ... }`.
|
|
|
|
## Lectura (GET) — siempre permitida
|
|
|
|
### Estado y metadata
|
|
| Endpoint | Devuelve |
|
|
|---|---|
|
|
| `GET /status` | `{ object, status: locked\|unlocked, serverUrl, userEmail, userId, lastSync }` |
|
|
| `GET /sync` | Fuerza sync con el server. `{ object: "message", title: "Syncing complete." }` |
|
|
| `GET /object/fingerprint/me` | Fingerprint phrase de la cuenta |
|
|
|
|
### Listas
|
|
| Endpoint | Filtros (querystring) |
|
|
|---|---|
|
|
| `GET /list/object/items` | `search`, `url`, `folderid`, `collectionid`, `organizationid`, `trash` |
|
|
| `GET /list/object/folders` | `search` |
|
|
| `GET /list/object/collections` | `search`, `organizationid` |
|
|
| `GET /list/object/org-collections` | `organizationid` (requerido) |
|
|
| `GET /list/object/org-members` | `organizationid` (requerido) |
|
|
| `GET /list/object/organizations` | `search` |
|
|
| `GET /list/object/sends` | `search` |
|
|
|
|
### Objeto específico (por id o por search exact-match en name)
|
|
| Endpoint | Notas |
|
|
|---|---|
|
|
| `GET /object/item/<id\|name>` | Item completo (login/note/card/identity) |
|
|
| `GET /object/folder/<id\|name>` | Folder |
|
|
| `GET /object/collection/<id>` | Collection (personal o org) |
|
|
| `GET /object/org-collection/<id>?organizationid=X` | Collection del org con detalles de members |
|
|
| `GET /object/send/<id\|name>` | Send |
|
|
| `GET /object/password/<item-id>` | **Sólo el password en plaintext** |
|
|
| `GET /object/username/<item-id>` | Sólo el username |
|
|
| `GET /object/uri/<item-id>` | Primera URI del item |
|
|
| `GET /object/totp/<item-id>` | Código TOTP actual (si el item tiene `login.totp` configurado) |
|
|
| `GET /object/notes/<item-id>` | Texto de la nota |
|
|
| `GET /object/exposed/<item-id>` | Cuántas veces el password apareció en HIBP |
|
|
| `GET /object/attachment/<attachment-id>?itemid=X&output=path` | Descarga el attachment |
|
|
| `GET /object/template/<type>` | Template JSON para crear (`item`, `item.login`, `item.card`, `item.identity`, `item.securenote`, `folder`, `collection`, `send.text`, `send.file`, `org-collection`) |
|
|
|
|
### Generador
|
|
| Endpoint | Querystring |
|
|
|---|---|
|
|
| `GET /generate` | `length=20`, `uppercase`, `lowercase`, `numbers`, `special`, `passphrase=true`, `words=3`, `separator=-`, `capitalize`, `number` |
|
|
|
|
Ejemplo: `GET /generate?length=24&uppercase&lowercase&numbers&special`
|
|
|
|
## Creación (POST) — permitida en endpoints específicos
|
|
|
|
| Endpoint | Body | Devuelve |
|
|
|---|---|---|
|
|
| `POST /object/item` | item JSON (ver `GET /object/template/item`) | item creado con `id`, `revisionDate` |
|
|
| `POST /object/folder` | `{ "name": "..." }` | folder con `id` |
|
|
| `POST /object/send` | send JSON (`GET /object/template/send.text` o `send.file`) | send con `id`, `accessUrl` |
|
|
| `POST /object/org-collection?organizationid=X` | collection JSON | requiere permisos en el org (claudecode0 = "Can view" → 403) |
|
|
|
|
### Auth/utility (también POST permitido)
|
|
| Endpoint | Body | Notas |
|
|
|---|---|---|
|
|
| `POST /sync` | (vacío) | Equivalente a GET /sync |
|
|
| `POST /unlock` | `{ "password": "..." }` o vía `BW_SESSION` env | Devuelve nueva session |
|
|
| `POST /lock` | (vacío) | Lockea el vault. Requiere unlock para volver a usar |
|
|
| `POST /generate` | `{ length, uppercase, ... }` | Equivalente a GET /generate |
|
|
|
|
### Schema mínimo de item (type 1 = login)
|
|
```json
|
|
{
|
|
"organizationId": null,
|
|
"folderId": null,
|
|
"type": 1,
|
|
"name": "GitHub",
|
|
"notes": "personal account",
|
|
"favorite": false,
|
|
"fields": [
|
|
{ "name": "Custom Field", "value": "x", "type": 0 }
|
|
],
|
|
"login": {
|
|
"uris": [{ "uri": "https://github.com", "match": null }],
|
|
"username": "user",
|
|
"password": "***",
|
|
"totp": "otpauth://totp/..."
|
|
}
|
|
}
|
|
```
|
|
|
|
Tipos: `1`=Login, `2`=SecureNote, `3`=Card, `4`=Identity.
|
|
|
|
Para SecureNote usar `"type": 2` + `"secureNote": { "type": 0 }` en lugar de `login`.
|
|
|
|
Pedí `GET /object/template/item.login` (o `.card`, `.identity`, `.securenote`) para el schema exacto antes de POST.
|
|
|
|
## Bloqueado por la skill (read+create only)
|
|
|
|
| Verbo / endpoint | Por qué |
|
|
|---|---|
|
|
| `PUT /object/*` | Modifica items existentes |
|
|
| `DELETE /object/*` | Soft-delete (a Trash) |
|
|
| `POST /restore/item/<id>` | Restaura desde Trash |
|
|
| `POST /move/<ids>/<orgId>` | Comparte item al org |
|
|
| `POST /confirm/org-member/<id>` | Confirma member invite |
|
|
| `POST /object/attachment` (multipart) | Adjuntar archivos |
|
|
| `POST /object/share/*` | Si existe, comparte items |
|
|
|
|
Si **realmente** necesitás bypass-ear el guard (ej. cleanup), pidiéndoselo al usuario:
|
|
```bash
|
|
BITWARDENCLI_APPDATA_DIR=~/.claude/skills/bitwarden/.cache/bw \
|
|
BW_SESSION=$(cat ~/.claude/skills/bitwarden/.cache/session) \
|
|
bw <delete|edit|...>
|
|
```
|
|
|
|
## Códigos de error comunes
|
|
|
|
| HTTP | Causa | Qué hacer |
|
|
|---|---|---|
|
|
| 401 | Vault locked o session expirada | Re-correr `setup.sh` para re-unlock |
|
|
| 403 | Server side permission (rol "Can view" rechaza writes) | Esperado para acciones write en collections del org |
|
|
| 404 | Item/folder/collection no existe (o no tiene acceso) | Verificar id |
|
|
| 400 | Body JSON inválido | Pedí `GET /object/template/<type>` para el schema |
|
|
| 500 | bw serve crasheó | `serve-down.sh && serve-up.sh`, ver `.cache/serve.log` |
|
|
|
|
## Referencias
|
|
- Doc oficial CLI: https://bitwarden.com/help/cli/
|
|
- Vault Management API spec: https://bitwarden.com/help/vault-management-api/
|
|
- Vaultwarden compat: https://github.com/dani-garcia/vaultwarden
|