Itens

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.

Escopo

vault:read

Permissão

Ver o módulo

Tool do MCP

vault_items_listNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.list".

Custo declarado: até 1002 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

vault:read

Permissão

Ver o módulo

Tool do MCP

vault_items_getNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.get".

Custo declarado: até 203 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

vault:write

Permissão

Editar no módulo

Tool do MCP

vault_items_createNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.create".

Custo declarado: até 253 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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"
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

vault:write

Permissão

Editar no módulo

Tool do MCP

vault_items_updateNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.update".

Custo declarado: até 253 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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": {}
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Com uma API key, este DELETE roda direto: o registro fica 30 dias na lixeira e a resposta traz o seu trash_item_id. Com um token OAuth, e pelo MCP, pede dry_run → confirm_token.

Escopo

vault:write e «Permitir exclusões» (vault:delete no OAuth)

Permissão

Editar no módulo

Tool do MCP

vault_items_deleteNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.delete".

Custo declarado: até 1 leituras e 2 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

vault:write e «Permitir exclusões» (vault:delete no OAuth)

Permissão

Editar no módulo

Tool do MCP

vault_items_bulk_deleteNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.bulk.delete".

Custo declarado: até 500 leituras e 1000 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

vault:write

Permissão

Editar no módulo

Tool do MCP

vault_items_bulk_update_labelsNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.bulk.update_labels".

Custo declarado: até 550 leituras e 500 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

vault:read

Permissão

Ver o módulo

Tool do MCP

vault_items_audit_listNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.audit.list".

Custo declarado: até 12 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

vault:read

Permissão

Ver o módulo

Tool do MCP

vault_items_reveal_secretNa superfície completa; na compacta, mb_execute_operation com id: "vault.items.reveal_secret".

Custo declarado: até 3 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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