Skip to main content
Closed beta. Authenticated APIs are not yet generally available. The surface described here is live in production, but access is gated to a small group of design partners while the build pipeline matures. If you want to try it, reach out at kaan@peel.sh. Do not build production integrations against it until it exits beta.
Authenticated runtime support is intentionally narrow. Peel exposes it only when build time found a concrete protected request surface and published it as explicit endpoints. This page assumes you already know the difference between host auth (how you call Peel) and target-site auth (session_required). If not, start with Authentication.
This is not generic login automation. Peel does not support arbitrary browser login flows, page-by-page navigation, or open-ended authenticated browsing at runtime.

​
The published contract

API detail responses expose the boundary directly:
  • api.auth_mode
  • api.auth
  • api.requires_session
  • api.user_input_prompt
  • Per endpoint: endpoint_type and auth_requirement
{
  "auth_mode": "managed_session_only",
  "auth": {
    "capability_summary": "managed_session_only",
    "families": [
      {
        "session_tag": "orders_session",
        "login_endpoints": ["login"],
        "protected_endpoints": ["get_orders"],
        "verification_status": "structurally_verified",
        "user_input_required": false
      }
    ],
    "requires_managed_session": true,
    "user_input_required": false
  },
  "requires_session": true,
  "endpoints": [
    {
      "endpoint_name": "login",
      "endpoint_type": "login",
      "auth_requirement": "public"
    },
    {
      "endpoint_name": "get_orders",
      "endpoint_type": "data",
      "auth_requirement": "session_required"
    }
  ]
}
endpoint_type: "login" creates the session. auth_requirement: "session_required" marks protected calls that need that session. auth_mode is a derived capability summary with three values:
  • public — no session required.
  • mixed_public_and_managed_session — some endpoints are public, others need a session.
  • managed_session_only — every endpoint on the API is session-gated.
Use api.auth when you need the compiled family view: which login endpoint pairs with which protected endpoints, whether user input is still required, and how much verification the compiled flow has. verification_status on each family has three possible values:
  • unverified — Peel compiled the login flow structurally but has not exercised it. Runtime calls may fail for reasons the build did not catch.
  • structurally_verified — the compiled login and protected endpoints line up correctly by shape, including selectors, request bodies, and expected cookies, but no real credentials have been replayed against the target. Treat this as worth testing against a real account.
  • credential_verified — the build replayed the full flow with real credentials at build time, and the compiled endpoints returned the expected shape. This is the highest-confidence tier.
If a protected build pauses for missing credentials or disambiguation, resume it through /v1/apis/{api_id}/respond over REST or respond_to_api_input over MCP before retrying runtime calls.

​
REST flow

curl -X POST "$PEEL_API_BASE/v1/apis/$API_ID/endpoints/login:call" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "your-password" }'

{
  "status": "success",
  "status_code": 200,
  "data": {},
  "initiates_session": true,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "encryption_key": "gAAAAABk..."
}
For protected REST endpoints, send session credentials with headers: 
curl -X POST "$PEEL_API_BASE/v1/apis/$API_ID/endpoints/get_orders:call" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Session-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Encryption-Key: gAAAAABk..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "shipped", "limit": 5 }'
Headers are the canonical transport for session credentials. Body fields work as a fallback. See Authentication for precedence rules. If either credential is missing, the call fails before target transport execution.

​
MCP shape

call_endpoint is invoked over JSON-RPC at POST https://api.peel.sh/mcp. Session credentials live at the top of arguments alongside api_id and endpoint_name. The endpoint’s own params go under a nested params object: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_endpoint",
    "arguments": {
      "api_id": "550e8400-e29b-41d4-a716-446655440000",
      "endpoint_name": "get_orders",
      "session_id": "550e8400-...",
      "encryption_key": "gAAAAABk...",
      "params": {
        "status": "shipped",
        "limit": 5
      }
    }
  }
}

​
What this means operationally

  • Host auth gets you into Peel. It does not create a target-site session.
  • The login endpoint creates the target-site session.
  • Protected behavior must already be compiled into explicit endpoints.
  • Not every site can be expressed this way.
For the broader runtime boundary, see Deterministic Runtime. For host-side auth, see Authentication.