Economico authentication and permissions

Economico authenticates MCP, REST and CLI callers through the same OAuth resource, https://economi.co/mcp. Every business call is authorized against live membership, the application’s grant and the token’s permissions.

Interactive access

Use the CLI’s login or your MCP host’s OAuth flow. Economico supports the authorization-code flow with PKCE. Request the mcp scope and the exact resource https://economi.co/mcp. The signed-in person approves business access.

Discovery documents are public:

curl https://economi.co/.well-known/oauth-authorization-server
curl https://economi.co/.well-known/oauth-protected-resource/mcp

Use the endpoints and supported methods advertised by those documents. A 401 response includes a WWW-Authenticate resource metadata URL. Never send a token to another origin or infer authority from a business slug.

Effective permissions

A token has no implicit current business. MCP tools name it with business; REST requests use X-Economico-Business. The catalog is filtered for that connection, and execution checks permissions again. Startup supports scoped access for connected agents. A connection can be approved for several businesses.

Membership changes, ownership transfer, public-access policy and cancellation approval require a signed-in human. Signup and supported platform-plan purchases can be completed by an authenticated agent with the owner’s authority.

Unattended agents

Registered headless clients exchange a signed private_key_jwt assertion using client_credentials at /oauth/headless/token. Keep private keys local and use only public verification keys in registration. The issued token is bound to the same MCP resource and carries the approved per-business grant. See the setup guide’s headless instructions.

Agent signup

An agent can create a Solo company using /oauth/agent/signup/start, verify, offer and accept. Start with a recovery email and public JWKS. The email recipient or an authorized recovery channel supplies the emailed code. Each continuation is a short-lived bearer credential for this signup, never a browser session or permission to reach an existing business.

Review the returned offer and accept its exact identifier and CID only with the owner’s authority. Acceptance returns the business slug, client identifier and token endpoint. Use the issued headless grant for subsequent calls. A Startup upgrade is a separate offer and payment flow through platform_purchase.

Recovery

Reconnect after revocation or an invalid token. A 403 means the current caller cannot perform the operation; do not retry with broader access automatically. On 429, wait for Retry-After before retrying. Connections and headless grants can be revoked from account controls. See API errors.