Tools & scopes
What an agent can do through the ApiVault MCP server: the tools it can call, the OAuth scopes that unlock them, and the errors it gets back when a call is refused.
Available tools
The server exposes six dedicated tools for browsing masked metadata, managing vault credentials, and decrypting secrets on-demand:
| Tool | Required Scope | Description |
|---|---|---|
list_keys | keys:read | List API keys with masked previews (sk_live_••••1234). Supports filtering by environment or service. |
get_key | keys:read | Retrieve metadata and masked preview for a single key by ID. |
reveal_key | keys:reveal | Decrypt and return the raw secret value. Accepts optional vault_key for custom encryption accounts. |
add_key | keys:write | Store a newly generated API key in the encrypted vault. |
update_key | keys:write | Update metadata or re-encrypt secret values for an existing key. |
delete_key | keys:write | Permanently remove a key from the vault by ID. |
OAuth scopes
During OAuth consent you select which permissions to grant:
Claude Desktop. That is why the name carries an Unverified badge. The consent screen also shows a Redirects to row with the origin the authorization code will be sent to. Approve only when that origin matches the tool you started the connection from, and treat a destination that is not using HTTPS as suspect.The client icon is picked from the first source that loads: the logo_uri sent at registration, the favicon of its client_uri or of its HTTPS redirect URIs, a LobeHub icon matching the client name, a built-in icon for well-known clients, and finally a generic MCP icon. Only HTTPS logo_uri and client_uri values are stored.
| Scope | Permission | Tools |
|---|---|---|
keys:read | View API keys (masked) | list_keys, get_key |
keys:write | Add, update, and delete API keys | add_key, update_key, delete_key |
keys:reveal | Reveal decrypted secret values | reveal_key |
Manage or revoke connected agents anytime in Settings → MCP Connections.
Error codes
| Code | Meaning | Action |
|---|---|---|
UNAUTHORIZED | Token missing or expired | Trigger re-authentication in your client |
INSUFFICIENT_SCOPE | Token lacks required scope | Re-authenticate with write or reveal scope granted |
NOT_FOUND | Key ID invalid | Re-list keys with list_keys |
VAULT_KEY_REQUIRED | Custom encryption; vault key needed | Pass vault_key in tool arguments |
INVALID_VAULT_KEY | Wrong custom vault key | Supply the correct vault key — repeated wrong guesses are throttled |
VAULT_KEY_RATE_LIMITED | Too many incorrect vault keys | Wait for the delay in the error message before retrying |
DUPLICATE_KEY | Key with same name & environment exists | Use update_key or choose another name |
Vault key attempt limits
A custom vault key is verified against a stored hash, so incorrect keys passed to reveal_key, add_key or update_key are rate limited: 10 failures per 15 minutes, counted per user and per source address. Exceeding the limit returns VAULT_KEY_RATE_LIMITED (HTTP 429 with a Retry-After header), and the tool error states how long to wait.
A correct vault key clears the counter, so an agent that reveals several keys in a row is never throttled. Agents should not retry a rejected vault_keyautomatically — ask the user for the correct one instead.
Rejected attempts are visible, not silent: a failed tool call is written to the project's audit log with its HTTP status, the error code above, the acting user and the client name the agent reports, filed under the action that was attempted — so a denied reveal_key appears as a KEY_REVEALED entry with a 4xx status. Calls rejected before a project can be resolved are not logged, because entries are stored per project.