Authentication

MCP initialization, tool discovery, and public model discovery do not require authentication. Account access and all paid MCP or CLI execution requests require a PoYo API key.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

A successful model search does not confirm that the configured API key is valid. Use poyo_account or poyo auth status to verify authentication.

CLI

Store the key in the system keyring:

poyo auth login

For an ephemeral environment:

export POYO_API_KEY="YOUR_API_KEY"

Credential priority is --api-key, POYO_API_KEY, system keyring, then local config fallback.

Security

Never include a key in an MCP URL or prompt.
Never commit a key to MCP configuration.
Prefer environment interpolation when configuring a client.
Apply API-key model and credit limits in the PoYo dashboard.

Authentication failures

REST requests use an HTTP 401 response:

{
  "code": 401,
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}

MCP business and authentication failures are returned as Tool Results with isError: true, even when the MCP HTTP transport itself returns 200. Clients should inspect the tool result instead of relying only on the HTTP status.

​Authentication

​CLI

​Security

​Authentication failures

Authentication

CLI

Security

Authentication failures