> ## 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 MCP: https://mcp.melso.ai/mcp (OAuth; one company per connection). Documentation-search MCP: https://docs.melso.ai/mcp; it does not act on customer accounts.
>
> Use the live tool list and respect company membership. Ask the person to approve the exact invoice or tax return version in the signed-in app. Melso's professionals prepare and file included returns after approval; an AI assistant does not file. A prepared file or an approval is not evidence of filing: only the AEAT's reference and receipt are. Keep credentials out of chat and logs.

# Authentication

> Partner keys, test and live mode, how a call is scoped to one company, and the decisions a key can never make.

<Info>
  Partner keys are issued when your partner account is enabled. See
  [Availability](/api/availability).
</Info>

Every request carries your partner secret key as a bearer token:

```bash theme={null}
curl https://api.melso.ai/v1/companies \
  -H "Authorization: Bearer $MELSO_PARTNER_KEY"
```

## Keys

| Key | Works on | Use it for |
| - | - | - |
| `mk_test_…` | Test companies only | Building and CI. Nothing reaches an administration, nothing is billed. |
| `mk_live_…` | Real companies | Production. Filings are real. |

A key is a secret for your servers. Do not put it in a browser, a mobile app
or a log. Create, rotate and revoke keys from your partner dashboard; a revoked
key stops working at once. Each key can be limited to the modules you use, such
as payroll only.

## One company per call

Every company-scoped path names the company:
`/v1/companies/{company_id}/…`. A call works in that company and nowhere else.
A company that is not on your partner account answers `404`, the same as one
that does not exist.

Keep the `id` Melso returns when you create the company, or set your own
`external_id` and look the company up with it.

## What a key cannot do

A key acts for your platform, not for a person. Three kinds of decision belong
to a person at the company, and no key can make them:

| Decision | How the person makes it |
| - | - |
| Issue an invoice | On Melso's approval page, from an [approval link](/api/reference/invoices/create-invoice-approval-link) |
| Approve a tax return or a case | On Melso's approval page, or in your product under a partner agreement ([attested approval](/api/reference/tax-returns/attest-tax-return-approval)) |
| Sign a mandate | On Melso's hosted signing page, from a [mandate](/api/reference/mandates/create-mandate) |

Operations that need a person carry a **A person decides** notice in the
reference. Calling one with a key answers `403` with `code`
`person_required`. See [Approvals and filing](/api/approvals).

## Errors

| Status | Meaning |
| - | - |
| `401` | The key is missing, revoked or invalid. |
| `403` | The key cannot do this: a module it is not enabled for, or a decision for a person. |
| `404` | No such object in this company, or the company is not yours. |

See [Conventions](/api/conventions) for the error format.


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