Skip to main content
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.

​
Credential types

Company keys imply their company. Omit X-Workspace-ID; a header naming a different company returns 403 workspace_key_scope. A key acts as its own integration identity, not as the person who created it. Tasks and Runs keep that attribution. Funding uses the identity’s own policy, with no member’s subscription account, long-term memories or connected apps. See Execution funding.

​
Handle tokens securely

For services, inject credentials from a secret manager. For a local Bash session, the hidden prompt below avoids putting a personal token in terminal history. Use MELSO_URL as the origin, following the base URL convention, and replace the company UUID:
Environment variables are still available to child processes. Use a trusted computer, keep shell tracing (set -x) off, and never print credentials or include them in chat, source control or logs. Run unset MELSO_TOKEN when finished. The API quickstart uses the same approach for a company key.

​
Company key scopes

The scope is fixed when the key is created; create another key to change it. tasks is the default. Both scopes reach Task and Run routes, their permitted messages and interactions, the Task stream, file uploads and downloads, model discovery, Cloud capabilities, GET /api/me, their own company, the Area reads below, an empty connected-app list, and their own harness policy. admin also reaches these administration routes for its own company:
  • GET /api/workspaces/{id}/members (people, excluding key identities).
  • GET /api/workspaces/{id}/github/installations and GET /api/workspaces/{id}/github/installations/{installationId}/repositories.
  • GET, PUT and DELETE /api/workspaces/{id}/private-network.
  • The Area administration routes in the next table.
  • GET /api/tasks/{id}/pull-requests, GET /api/pull-requests/resolve, GET /api/pull-requests/{id}, and POST /api/pull-requests/{id}/merge.
  • GET and PUT /api/secrets/repository.
  • Its own permitted provider-account, managed execution identity and repository credential broker routes. On supported account and funding routes, X-Execution-Identity-ID selects a managed customer owned by that integration. Without one, its account list is empty and starting a subscription connection returns 403 provider_account_workspace_key.
An admin key acts as a company admin only on the listed administration routes. It is never an owner, and its Runs retain member authority. Routes outside its scope return 403 workspace_key_scope. This includes API-key management, member/role/invitation management, billing, company settings and deletion, general vault, Automation and webhook management, and the MCP endpoint. A tasks key also receives that error on admin-only routes. Scope errors explains the shared code for these denials and a mismatched company.

​
Webhook management credentials

All webhook management routes, including endpoint reads, delivery logs, resends and signing-secret rotation, require a human company owner/admin. Use a human owner/admin credential to register the receiver and obtain its signing secret. A company key can create Tasks within its scope, but it cannot manage webhook endpoints.

​
Area routes by key scope

Allowed reads still enforce resource access. Area writes require an Agents company and company definition write permission. For people, this means owner/admin; company keys reach only their allowlisted routes. Resource reads are admin-only for keys; an authorized human member can read accessible resources.

​
Credential lifecycle and boundaries

Revoking a company key stops new API calls and removes provider API keys saved in its funding policy. Runs already executing finish. Human owners/admins can rotate a key; rotation returns the new token once, immediately invalidates the old token, and preserves its identity, scope and expiry. Expired or revoked keys cannot be revived by rotation. Store the returned token in your backend’s secret store. Run tokens cannot use human-only routes. Within their allowed scope, Runs can start, resume, rerun and message Tasks; Run rate limits also apply. Isolated Runs have narrower permissions. MCP OAuth grants cannot switch companies through a header or tool argument; authorize another connection instead. Personal tokens and company keys cannot authenticate MCP calls. See the Authentication endpoints for token and key request/response schemas. Request conventions have their own references: Errors, Rate limits, Idempotency, and Pagination.