Skip to main content
Peel has two separate auth layers:
  • Host auth: who is allowed to call Peel.
  • Target-site session auth (session_required): credentials some compiled endpoints need for the target site.
The CLI uses the same host auth model, then stores the resulting API key locally for later REST and MCP calls.

​
Host auth to call Peel

For external REST usage, authenticate to Peel with X-API-Key: 
curl -H "X-API-Key: $PEEL_API_KEY" "$PEEL_API_BASE/v1/apis"
X-API-Key identifies the Peel actor that owns the API, is billed for calls, and can revise or rebuild it. Public /v1/apis/... routes can also be called from the first-party app with session auth, but that is a host-side app session, not target-site auth.

​
CLI auth

The CLI defaults to https://api.peel.sh for API requests and supports two host-auth paths:
  • peel auth login for browser device flow
  • peel auth login --api-key ... for direct key injection
The OpenAPI bundle includes the CLI-facing device helpers, POST /public/device/start and POST /public/device/exchange. The signed-in browser approval step is handled by the first-party Peel app. 
peel auth login
peel auth login --api-key sk_...
peel auth status
peel auth logout
peel setup wraps this flow and then continues with MCP install plus doctor checks.

​
Headless signup

If the target deployment allows public signup, the CLI also supports: 
peel auth signup --email you@example.com --password 'secret123'
If signup is disabled, the command fails cleanly and tells you to use an existing account instead.
On peel.sh, public signup is disabled during private preview. Use an existing account, then create API keys from settings. Headless signup only applies to deployments where an operator enabled public signup.

​
MCP auth

/mcp accepts either:
  • X-API-Key
  • Authorization: Bearer ... for MCP OAuth clients
{
  "mcpServers": {
    "peel": {
      "url": "https://api.peel.sh/mcp",
      "headers": {
        "X-API-Key": "YOUR_PEEL_API_KEY"
      }
    }
  }
}
OAuth bearer tokens authenticate to the Peel host only. They do not replace session_id and encryption_key for protected target-site endpoints.

​
session_required is a second layer

Some compiled APIs publish a deterministic login endpoint and one or more protected endpoints.
  • The login endpoint returns session_id, encryption_key, and initiates_session: true.
  • Protected endpoints require both values on every call.
This layer authenticates to the target site. It does not authenticate you to Peel itself.

​
REST session credentials

For POST /v1/apis/{api_id}/endpoints/{endpoint_name}:call, runtime accepts session credentials in either place:
  • Preferred headers: X-Session-ID and X-Encryption-Key
  • Request body fields: session_id and encryption_key
Headers win if both are present. 
curl -X POST "$PEEL_API_BASE/v1/apis/$API_ID/endpoints/login:call" \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"***"}'

curl -X POST "$PEEL_API_BASE/v1/apis/$API_ID/endpoints/inbox:call" \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "X-Session-ID: SESSION_ID" \
  -H "X-Encryption-Key: ENCRYPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folder":"inbox"}'

​
MCP session credentials

call_endpoint takes session credentials as top-level tool arguments, with endpoint params nested under params. The shape below is the arguments object inside a JSON-RPC tools/call request. See Authenticated APIs for the full envelope. 
{
  "name": "call_endpoint",
  "arguments": {
    "api_id": "550e8400-e29b-41d4-a716-446655440000",
    "endpoint_name": "inbox",
    "session_id": "SESSION_ID",
    "encryption_key": "ENCRYPTION_KEY",
    "params": {
      "folder": "inbox"
    }
  }
}

​
Production guidance

  • Treat X-API-Key as the primary deployment secret. Rotate it with your normal secret-management process.
  • Keep session values (session_id, encryption_key) transient. Do not persist them outside your trusted runtime.
  • If a site cannot be reduced to a compiled login plus deterministic protected calls, it is not a supported session_required surface.

​
Calling Peel from a browser

api.peel.sh runs with a strict CORS allowlist. By default, only the Peel SPA at https://peel.sh is allowed, with credentials. Arbitrary third-party origins are rejected. Two rules of thumb:
  • Never ship X-API-Key in client-side JavaScript. Keys are deployment secrets. Call Peel from your server and expose a scoped proxy route to your frontend.
  • If you need browser-to-Peel calls from your own origin, email kaan@peel.sh to get your domain added to the allowlist. This is a one-off configuration change, not a self-service setting.