Access requests

List the vault's access requests

vault.requests.list

Lists the access requests (Request access: a one-time link where a client enters the credentials the agency needs), newest first, paginated by cursor (limit up to 200), of the chosen scope: open (default; pending) or closed (fulfilled, revoked or expired). Each request: the client account (assigned_child_org_id) and the name written on the request (child_org_name: what the client sees), the slots asked for (id, type, title), message, the recipient written down, status, expires_at, who created it and when, and once fulfilled, fulfilled_at, fulfilled_item_ids (the credentials it created, see vault.items.get) and the name and email the client left. It never returns the link or its code. A request past its expiry is reported (and saved) as expired, and the page is completed reading up to 400 requests. Requires view access to the Vault.

Scope

vault:read

Permission

View the module

MCP tool

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

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/vault/requests" \
  -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/requests" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Ask a client for credentials through a one-time link

vault.requests.create

Creates an access request: a one-time link (expires_in_ms: 86400000 for 24 h, 604800000 for 7 d or 2592000000 for 30 d) where the client enters the credentials asked for in slots (1 to 10; type ftp, login, hosting_panel, database, ssh, api_key or note for «other access», each with a title such as «acme.com — FTP»). What the client submits is encrypted on arrival and stored in the Vault assigned to the client account, and the creator gets an in-app and email notice (vault.access.fulfilled fires). In a workspace, assigned_child_org_id is required and must be one of its accounts (vault_request_account_required, vault_account_invalid); elsewhere it is ignored. Optional message, recipient (name, email) and locale (es, en, pt-BR) of the public page and of the email. Through an API key, an OAuth app or any other credential the response does NOT include the link (a bearer URL): to get it to the client, write down recipient.email here and call vault.requests.send_email (MB Suite emails the link to that address), or the person copies it from the app (Vault → Requests → Copy link). Requires edit access to the Vault.

Scope

vault:write

Permission

Edit in the module

MCP tool

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

Events it can emit

vault.access.requested

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

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/vault/requests" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "slots": [],
  "expires_in_ms": "86400000"
}'

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/requests" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "slots": [],
  "expires_in_ms": "86400000"
}'

Revoke a pending access request

vault.requests.revoke

Closes a pending access request at once: its link shows the neutral «not available» page and the client can no longer submit. Only its creator, an owner or an admin (vault_link_not_owner, 403). Idempotent: on a request that is no longer pending (fulfilled, revoked or expired) nothing changes (changed=false). Credentials already received stay in the Vault. Returns the request. Requires edit access to the Vault.

Scope

vault:write

Permission

Edit in the module

MCP tool

vault_requests_revokeOn the full surface; on the compact one, mb_execute_operation with id: "vault.requests.revoke".

Declared cost: up to 1 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/requests/{request_id}/revoke" \
  -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/requests/{request_id}/revoke" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Email a pending access request to its recipient

vault.requests.send_email

MB Suite emails a pending access request to the recipient written down when it was created (recipient.email): the email, in the request's language, says who asks for which client account, lists what is asked for, shows the message and carries the one-time secure link, with its expiry. It is sent through MB Suite's email (from the organization's own verified sending domain when it has one). The link only travels inside that email: the response says who it was sent to (sent_to, sent_at, send_count) and never returns the link; the email log keeps it masked. It goes only to the address on the request: to send it elsewhere, create a new request with that recipient. Only its creator, an owner or an admin (vault_link_not_owner, 403); the request must be pending (vault_request_not_pending, 409) and have a recipient email (vault_request_recipient_email_required, 400), which cannot be the person behind the API key or app (400 vault_request_recipient_is_self; compared without case, +tags and, in Gmail, dots). At most once a minute (429 cooldown_active), 5 times per request (409 limit_reached) and 50 emails per UTC day per organization and per API key or app, a workspace key counting once across its accounts (429 daily_limit_reached, details.scope organization or credential, retry_after until 00:00 UTC); 409 vault_request_email_unavailable while emailing requests is not available. Outside the app it always takes two steps: dry_run=true says who it would go to and when the link expires, without sending, and returns the confirm_token that sends it. If the email provider does not send it (details.platform ses): 503 external_unavailable or 429 external_rate_limited, retry later; 409 external_rejected when it refuses the address; 409 external_outcome_unknown when it may have gone out (check before sending again). 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_requests_send_emailOn the full surface; on the compact one, mb_execute_operation with id: "vault.requests.send_email".

Declared cost: up to 6 reads and 3 writes per call (they count against the daily quota). Touches an external platform (ses): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/vault/requests/{request_id}/send-email" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.