API and MCP
Version 0.11
Give a script, a CI pipeline or an AI assistant access to one project. Items stay end-to-end encrypted: the API key itself decrypts them on your machine, and our server never sees the plaintext.
API keys
A project manager creates keys on the project page in the web vault (section API keys). Each key:
- opens one project and nothing else (no personal items, no other projects);
- has a permission: Can view (read), Can edit (read, add, change, delete items) or Manage (also add and remove people);
- can expire after 1 week, 15 days, 1 month or 1 year, or never;
- acts for the manager who created it: if that person loses access to the project, the key stops working;
- is shown once. Deleting it cuts access immediately. Every use is in the project activity log, marked API or MCP.
A key looks like bwv_<id>.<secret>. Store it like a password, for example as a CI secret or an environment variable.
MCP server (Claude, Cursor and other AI assistants)
The MCP server runs on your computer, so items are decrypted locally. It is one file with no dependencies and needs Node.js 20 or newer.
- Download vault-mcp.mjs.
- Create an API key for the project. Use Can view unless the assistant should change things.
- Add it to your assistant.
Claude Code:
claude mcp add brahmweb-vault --env VAULT_API_KEY=bwv_... -- node /path/to/vault-mcp.mjs
Claude Desktop, Cursor, Windsurf (the mcpServers section of the config file):
{
"mcpServers": {
"brahmweb-vault": {
"command": "node",
"args": ["/path/to/vault-mcp.mjs"],
"env": { "VAULT_API_KEY": "bwv_..." }
}
}
}
Self-hosted server? Also set VAULT_SERVER to its address.
| Tool | What it does | Key needs |
|---|---|---|
vault_info | Project, permission and expiry of the key | view |
list_items | Names, websites, usernames and variable names (no secrets) | view |
get_item | One item with its password or variables | view |
get_env_file | Environment variables as .env text | view |
generate_password | A strong random password | view |
list_members | People in the project, permission, expiry | view |
save_login | Create or update a login | edit |
save_env | Create or update environment variables (replace or merge) | edit |
delete_item | Delete an item for everyone in the project | edit |
share_project | Add a person or change their permission and expiry | manage |
remove_member | Remove a person | manage |
project_activity | Recent audit log | manage |
Authentication
Base URL: https://vault.brahmweb.com. All requests and responses are JSON. The secret part of the key is never sent. Your client derives two values from it with HKDF-SHA256 (32 zero bytes as salt):
auth= HKDF(secret, info"vault-api-auth"), 32 bytes, base64url without padding. SendAuthorization: Bearer bwv_<id>.<auth>.K= HKDF(secret, info"vault-api-key"), 32 bytes, an AES-256-GCM key. It stays on your machine.
The secret in the key is base64url. Optionally send X-Vault-Client: mcp to label your calls as MCP in the activity log.
Encryption format
- Encrypted values are
<iv>.<ciphertext>: standard base64, a 12-byte IV, AES-256-GCM with the tag appended. GET /api/v1/keyreturnswrappedKey. Decrypt it withKto get the 32-byte project keyP.- Each item's
datais a JSON object encrypted withP:{ type: "login", name, url, username, password, notes }or{ type: "env", name, vars: [{ key, value }], notes }. - Optional
labelon writes:{ "n": name }encrypted withP, so the activity log can show the item name to managers. - Handing the project key to a new member: RSA-OAEP with SHA-256, using the member's
publicKey(SPKI, base64).
Endpoints
| Call | Body | Returns | Key needs |
|---|---|---|---|
GET /api/v1/key | { id, name, role, projectId, projectName, orgName, wrappedKey, expiresAt } | view | |
GET /api/items | [{ id, data, projectId, role, updatedAt, lastUsedAt, lastUsedBy }] | view | |
POST /api/items/activity | { id } | Usage log of one item | view |
POST /api/projects/members | { projectId } | [{ email, name, role, expiresAt, active, publicKey }] | view |
PUT /api/items | { id?, data, label? } | { id } (no id creates) | edit |
DELETE /api/items | { id, label? } | {} | edit |
POST /api/projects/add | { projectId, email, role, expiresAt } | {}. expiresAt is ms since 1970 or null | manage |
POST /api/projects/remove | { projectId, email } | {} | manage |
GET /api/keys/pending | { projects: [{ projectId, email, publicKey }] } | manage | |
POST /api/keys/complete | { projects: [{ projectId, email, wrappedKey }] } | { done } | manage |
POST /api/projects/activity | { projectId } | Project audit log | manage |
After projects/add, people who already have a confirmed account appear in keys/pending. Wrap P with their public key and send it to keys/complete to start their access. New people get an email invite first.
Rate limits and errors
- API keys: 120 requests a minute per key. Signed-in apps: 600 a minute per session. Public endpoints: 120 a minute per IP address, and stricter limits on sign-up, login and codes.
- Over the limit you get
429with aRetry-Afterheader in seconds. - Errors are
{ "error": "message" }:400bad input,401invalid, expired or deleted key,403not allowed for this key or project,404unknown endpoint.
Security
- Zero-knowledge: the server stores a hash of
authand the project key encrypted withK. A database leak reveals neither the key nor the items. - Give each pipeline or assistant its own key with the lowest permission and an expiry, so you can see and cut each one separately.
- Anyone holding a key can read the project. If one leaks, delete it on the project page and change the passwords it could read.
- Found a security problem? Write to info@brahmweb.com.