Items

List vault credentials (metadata only)

vault.items.list

Lists the credentials stored in the organization's Vault (FTP, SSH, hosting panels, databases, logins, API keys, Wi-Fi, notes), newest first, paginated by cursor (limit up to 200). Each one comes with its metadata: title, type, username, host, port, URL, labels, client account (assigned_child_org_id), access mode (with custom access, access.grantee_count says how many people can open it; who and why, in vault.items.get), who created it and who changed it last (updated_by_name), has_secret and, when a client submitted it through an access request, received_via. assigned_child_org_name and assigned_child_org_status (active, archived or deleted) name the client account when it is one of this workspace's accounts (null otherwise). It NEVER returns a password or its ciphertext: passwords are only revealed in the MB Suite app, audited. Notes come only with include_notes: true (MIA never gets them in a list: it reads them one credential at a time with vault.items.get). Filters: type, assigned_child_org_id (an account id, or none for the agency's own credentials), label_id, search (words in any order, without case or accents, or a fragment, over title, username, host and URL). A credential with custom access is only usable by its creator, the people it lists, owners and admins (in an account, also the workspace's owners and admins) (vault_item_access_denied, 403, for anyone else; lists skip it). Filters and access apply to what is read, up to 600 credentials per call: keep following next_cursor while has_more is true. Requires view access to the Vault.

Scope

vault:read

Permission

View the module

MCP tool

vault_items_listOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.list".

Declared cost: up to 1002 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/vault/items" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/vault/items" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one vault credential (metadata and notes)

vault.items.get

Returns one credential of the Vault with its metadata and its notes (team-visible text, not a secret): title, type, username, host, port, URL, labels, client account, access, has_secret, shared_until (the latest expiry of the active secure links that include it) and received_via. assigned_child_org_name and assigned_child_org_status (active, archived or deleted) name the client account when it is one of this workspace's accounts (null otherwise). With custom access, access.grantees lists everyone who can open the credential today and why (via: creator, listed, owner, admin, workspace_owner, workspace_admin; name is the person's display name, never the email): they also need access to the Vault module, and MB Suite support can open it in the app. updated_by_name names who changed it last. It never returns the password or its ciphertext. vault_item_not_found (404) if the id does not exist in this organization. A credential with custom access is only usable by its creator, the people it lists, owners and admins (in an account, also the workspace's owners and admins) (vault_item_access_denied, 403, for anyone else; lists skip it). Requires view access to the Vault.

Scope

vault:read

Permission

View the module

MCP tool

vault_items_getOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.get".

Declared cost: up to 203 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/vault/items/{item_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/vault/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Store a credential in the vault

vault.items.create

Stores a credential in the Vault: title, type (login, ftp, ssh, database, hosting_panel, api_key, wifi, note), and optionally username, host, port, URL, the password (secret: encrypted with Cloud KMS envelope encryption before it is stored; it is never returned, not even here), notes (team-visible text, not encrypted: never put a password there), label_ids (from vault.labels.list), assigned_child_org_id (only in a workspace: one of its accounts) and access (default: everyone with access to the Vault; custom: only user_ids, plus the creator, owners and admins, and in an account the workspace's owners and admins). An empty secret stores the credential without a password. Errors: vault_account_invalid, vault_label_not_found, vault_access_user_invalid (400). Returns the new item_id and the credential's metadata (has_secret tells whether a password was stored). assigned_child_org_name and assigned_child_org_status (active, archived or deleted) name the client account when it is one of this workspace's accounts (null otherwise). With custom access, access.grantees lists everyone who can open the credential today and why (via: creator, listed, owner, admin, workspace_owner, workspace_admin; name is the person's display name, never the email): they also need access to the Vault module, and MB Suite support can open it in the app. updated_by_name names who changed it last. Requires edit access to the Vault.

Scope

vault:write

Permission

Edit in the module

MCP tool

vault_items_createOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.create".

Declared cost: up to 253 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/vault/items" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE",
  "type": "login"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/vault/items" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "TITLE",
  "type": "login"
}'

Update a vault credential

vault.items.update

Updates one or more fields of a credential (updates object): title, type, username, host, port (null removes it), url, notes, label_ids (replaces the whole list), assigned_child_org_id (null removes the client), access, and the password: secret with a new non-empty value re-encrypts it with Cloud KMS; an empty secret changes nothing; clear_secret: true removes the stored password (sending both is a 400 on updates.clear_secret). Changing or clearing the password leaves its own audit entry (security.vault_secret_rotated / vault_secret_cleared). Only what is sent changes. Returns the updated metadata, never the password. assigned_child_org_name and assigned_child_org_status (active, archived or deleted) name the client account when it is one of this workspace's accounts (null otherwise). With custom access, access.grantees lists everyone who can open the credential today and why (via: creator, listed, owner, admin, workspace_owner, workspace_admin; name is the person's display name, never the email): they also need access to the Vault module, and MB Suite support can open it in the app. updated_by_name names who changed it last. A credential with custom access is only usable by its creator, the people it lists, owners and admins (in an account, also the workspace's owners and admins) (vault_item_access_denied, 403, for anyone else; lists skip it). Requires edit access to the Vault.

Scope

vault:write

Permission

Edit in the module

MCP tool

vault_items_updateOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.update".

Declared cost: up to 253 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/vault/items/{item_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/vault/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a vault credential (to the trash)

vault.items.delete

Deletes a credential. It goes to the 30-day trash with its encrypted password, where an owner or admin can restore it with the same id (platform.trash.restore). A secure link that includes it skips it while it is deleted (a link left with nothing to show is revoked the next time someone opens it) and shows it again if it is restored. Outside the app it needs a dry run and a confirm_token, except a REST DELETE with a key allowed to delete. A credential with custom access is only usable by its creator, the people it lists, owners and admins (in an account, also the workspace's owners and admins) (vault_item_access_denied, 403, for anyone else; lists skip it). Requires edit access to the Vault.

With an API key, this DELETE runs directly: the record stays 30 days in the trash and the response carries its trash_item_id. With an OAuth token, and through the MCP, it needs dry_run → confirm_token.

Scope

vault:write and “Allow deletions” (vault:delete in OAuth)

Permission

Edit in the module

MCP tool

vault_items_deleteOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.delete".

Declared cost: up to 1 reads and 2 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/vault/items/{item_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/vault/items/{item_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete many vault credentials (to the trash)

vault.items.bulk.delete

Deletes up to 500 credentials at once; each one goes to the 30-day trash and can be restored on its own. Ids that do not exist or whose custom access does not include the caller are skipped and returned in skipped. Outside the app it requires a dry run (which lists what will be deleted) and a confirm_token. Requires edit access to the Vault.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

vault:write and “Allow deletions” (vault:delete in OAuth)

Permission

Edit in the module

MCP tool

vault_items_bulk_deleteOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.bulk.delete".

Declared cost: up to 500 reads and 1000 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/vault/items/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ],
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/vault/items/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ],
  "dry_run": true
}'

Add or remove labels on many vault credentials

vault.items.bulk.update_labels

Adds (to_add) and/or removes (to_remove) labels on up to 500 credentials at once, one write per credential. Labels to add must exist (vault.labels.list); unknown ones are ignored. Labels to remove may be any id (useful to clean one that no longer exists). Ids that do not exist or whose custom access does not include the caller are skipped and returned in skipped; credentials that already had the result are not rewritten. Outside the app it requires a dry run, which counts only the credentials that will change and names the unknown labels, and a confirm_token. Returns how many credentials changed. Requires edit access to the Vault.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

vault:write

Permission

Edit in the module

MCP tool

vault_items_bulk_update_labelsOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.bulk.update_labels".

Declared cost: up to 550 reads and 500 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/vault/items/bulk/labels" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ],
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/vault/items/bulk/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "item_ids": [
    "ITEM_ID"
  ],
  "dry_run": true
}'

List the access trail of a vault credential

vault.items.audit.list

Returns the latest audit entries of one credential (up to 100, newest first): who created, edited, revealed or copied its password, changed or cleared it, shared it through a secure link, revoked or copied that link, and when someone opened it from the public page (actor_uid public-link). Each entry: id, action (security.vault_*), actor_name, actor_uid, timestamp, plus via when it did not come from the app (api_key, mcp_key, oauth for a connected app through either door, mia, support; internal for anything else, such as a script) and key_name when an API key of this organization did it (including security.vault_secret_reveal_denied: a key with the reveal permission asked for a credential outside its list or without access). The same list the credential's Activity block shows in the app. A credential with custom access is only usable by its creator, the people it lists, owners and admins (in an account, also the workspace's owners and admins) (vault_item_access_denied, 403, for anyone else; lists skip it). Requires view access to the Vault.

Scope

vault:read

Permission

View the module

MCP tool

vault_items_audit_listOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.audit.list".

Declared cost: up to 12 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/vault/items/{item_id}/audit" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/vault/items/{item_id}/audit" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Reveal a credential's password with a key allowed to

vault.items.reveal_secret

Decrypts and returns the password of one Vault credential, only for an API key whose special permission vault_reveal (given on the key by an owner or admin) lists that credential, and only over REST on the key's own organization: the MCP, OAuth apps, MIA and keys without the permission never reach this operation (404). The key also needs the vault:read scope. An unknown credential gives 404 vault_item_not_found; a credential not in the key's list, or a call aimed at another organization, gives 403 vault_reveal_not_granted; the key's user must still be able to use the credential (403 vault_item_access_denied). At most 30 reveals per hour per person, across all of that person's keys, over a sliding hour (429 rate_limited with retry_after). Every reveal leaves a security.vault_secret_revealed audit entry with the key, and every request for a credential outside the list or without access a security.vault_secret_reveal_denied one, both visible in the credential's Activity (a 429 is not audited: it stays in the request log). Empty string when the credential has no password. An Idempotency-Key header is ignored: the response is never stored for retries.

Scope

vault:read

Permission

View the module

MCP tool

vault_items_reveal_secretOn the full surface; on the compact one, mb_execute_operation with id: "vault.items.reveal_secret".

Declared cost: up to 3 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/vault/items/{item_id}/secret" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/vault/items/{item_id}/secret" \
  -H "Authorization: Bearer $MB_TEST_KEY"