> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# Secrets

> Store write-only credentials and files, request values securely, and control access.

<Info>Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).</Info>

Secrets stores a company's logins, cards, text secrets such as API keys and tokens, and files such as service accounts and certificates. Each item has a `kind` (`login`, `card`, `text` or `file`) and a variable name, `env_name`. The member who saves an item owns it: their chat agent and every Run they start can use all of their items. `share` adds others: `private` (the default; nobody else), `workspace` (every Run in the company) or `areas` with `area_ids` (Runs in those Areas). The owner or a company owner/admin can change or delete an item. Admins see every item's metadata; members see their own items and the items shared with them. People manage items in **Settings → Secrets**, where what an agent asked them for waits at the top, under **Requested**.

A Run receives the items of the member who started it, the items shared with its Area and the items shared with the company. When two items use the same variable, the member's own item wins over an Area item, and an Area item over a company item. A `text` item arrives as the environment variable named by `env_name`. Logins, cards and files are written as private files for the Run, and `env_name` holds the file's path; login and card files are JSON. The Run's prompt lists item names, never values. Removing a member deletes their private items; items they shared stay with the company.

Repository variables are separate: `KEY=value` text written into one repository's checkout `.env` for Runs that check it out, never into the process environment and never into another repository. Company owners and admins manage them.

**Security.** Stored secret payloads are encrypted at rest (AES-256-GCM with a rotating keyring). They are write-only through the management API, CLI and MCP: those responses return metadata, not the saved payload. Authorized Runs receive the values as described above, and delivered values are redacted from Run output.

A secret request asks one member for a value. It waits in that member's **Settings → Secrets** until they save or dismiss it and never expires; its link, the returned `url` (including its company and request parameters), holds no credential, so only that member, signed in, can answer it. Asking again for the same thing returns the request that is already open. A request made from WhatsApp, Telegram or email gets the same signed-in link; the request is also listed on the member's Home. Saving resumes whoever asked: a Run's Task receives a follow-up and a chat agent is woken. Never ask for a secret in chat; send a link instead.

Metadata is readable by authorized viewers. `prefill.url` is the login website, separate from the returned request link. Melso removes URL user information, query parameters and fragments, but preserves the path. Use a normal login-page URL; do not put credentials or signed links in its path, names, notes, usernames or other metadata. The same rule applies to parent and reference fields in integrations: supply identifiers, never secret values. Write-only storage does not hide a secret copied into metadata.

<Warning>
  Saved values cannot be read back. Before replacing or deleting an item, keep any value you still need in your own secure store and check which Tasks use it. Removing a member also deletes their private items; shared items stay with the company.
</Warning>

**Cards.** Melso stores card numbers encrypted, but it is not a PCI-DSS certified card vault. Give agents virtual cards or cards with a low spending limit.

Run tokens (`mrt_…`) can list items, and create and list requests; every write, answering or dismissing a request included, rejects them with 403. Request bodies are strict JSON and unknown fields return 400. Use **Settings → Secrets** or the MCP `secrets` tool (actions `list`, `request`, `update` and `delete`); MCP `secrets_set`, for a value you already hold, is found with `tools_search` and called through `tools_call`.

## VaultRequestView

| Field | JSON type |
| - | - |
| `id` | string |
| `kind` | string |
| `status` | string: `pending`, `used` or `expired` |
| `prefill` | Readable metadata with `name`, `env_name`, login-site `url`, `username`, `cardholder` and `note`, each omitted when empty; never put secret values here. |
| `share` | string |
| `area_ids` | string\[] |
| `workspace_name` | string |
| `owner_name` | string |
| `expires_at` | string; empty for current signed-in requests, a timestamp for older public links |

Current signed-in requests have no expiry deadline. The `expired` status and a nonempty `expires_at` apply to older token-based links; see [Legacy secret links](#legacy-secret-links).

## API reference

Request fields, response types and endpoint permissions are defined in the [Vault reference](/api-reference/tags/vault). See [Pagination](/api-reference/pagination) for list conventions, or start with the [API quickstart](/api-reference/quickstart).

## Legacy secret links

New requests do not issue bearer-token links; they return a signed-in fulfillment URL with no expiry deadline. Token-based lookup and fulfillment remain only for pre-existing links. An unused, unexpired legacy token can still save the requested value; it is not read-only. Its `expires_at` is the deadline, and a used or expired link cannot fulfill the request again. Do not build a new integration around legacy tokens. Open the returned `url` so the intended person can sign in and respond.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.