X-API-Key: sk_urlapi_... or Authorization: Bearer sk_urlapi_..., on REST and MCP. MCP clients can sign in with OAuth instead.
Two separate layers
A Peel credential never signs you in to the target site, and a site session never authenticates you to Peel.
Authenticate REST requests
Create a key under API Keys in peel.sh settings, then send it on every request:200 with { "apis": [ ... ], "next_cursor": null }. GET /v1/apis accepts limit (1 to 100, default 50), cursor, status and include_archived (false, true or only).
The key identifies the account that owns your APIs, is billed for builds and calls, and can revise or rebuild them. Peel is in private preview and accounts are by invitation. Join the waitlist to get one.
Key access
Choose a key’s access when you create it. Access cannot be changed later; create a new key instead.
Building, revising and deleting APIs need
apis:write. Saved logins need logins:manage, webhooks need webhooks:manage, keys need keys:manage and team changes need team:manage, so only a full-access key reaches them today.
Manage keys over the API
A full-access key, or one withkeys:manage, can list, create, rotate and revoke keys, but never make a key with more access than its own. The secret appears once, in the answer to create or rotate. Lists show only its first characters.
Over MCP,
list_keys and revoke_key do the same. Creating and rotating stay on REST and in Settings, so a secret never passes through an agent’s context.
Keys for one API
Give an agent a key that can call and read one API and nothing else on your account. Sendapi_id when you create it; the API must be on the account you create the key for. From the CLI, peel keys create --name agent --access run --api <api-id>.
api_id shows in GET /v1/keys, and rotating keeps it. Its access still applies on top, so a read key limited to one API can read it but not call it. Over MCP it sees that API’s tools and the platform tools that stay on it; call_read_route refuses any route the key could not call directly.
A limited key cannot pass file handles as inputs, because files belong to the whole account. A file the endpoint saves during the same run can still be read back in that run. Use a key for the whole account for endpoints that take files.
An
Idempotency-Key belongs to the access of the key that first used it. Retrying with a key limited to a different API, or with a key for the whole account, answers 409 idempotency_scope_mismatch and runs nothing, so a limited key never receives a result made with wider access. A batch checks every item’s stored result first; if any item belongs to other access, the whole batch answers 409 and no item runs. The same holds for interactive executions. A retry with the same key and access returns the stored result even if the API was republished or its price changed in between.
Deleting the API stops new work at once: calls, batches, scheduled calls, executions, repair checks and MCP all refuse it, and any marketplace listing it published leaves the public catalog. Work admitted before the delete may finish and is billed as usual; an execution waiting for an answer stops when the answer arrives. The key itself is refused everywhere within 5 seconds, and during those seconds it can still read GET /v1/quota. Revoke it and create a new one.
Authenticate to the MCP server
POST https://api.peel.sh/mcp accepts either credential:
OAuth uses the authorization-code flow with PKCE (
S256) and refresh tokens. Peel publishes discovery documents at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource, supports dynamic client registration at POST /oauth/register, and serves /oauth/authorize, /oauth/token and /oauth/revoke.
A bearer token carries scopes. A tool call without the right scope returns 403.
Settings lists the apps you approved under Connected apps, with their scopes and when each last got a token. Disconnecting one deletes its tokens; it stops working within 5 seconds and needs your approval again to come back. The list is yours alone: it shows the same apps whichever team you are acting on, and an API key cannot read or change it.
Bearer tokens authenticate to Peel only. They do not replace
session_id and encryption_key for protected site endpoints. Client config blocks are in MCP server.
Call Peel from a browser
api.peel.sh allows browser requests only from https://peel.sh and origins its operator adds to an allowlist.
- Never put
X-API-Keyin client-side JavaScript. Call Peel from your server and expose your own scoped route to your frontend. - To call Peel from your own web origin, email kaan@peel.sh to ask for it to be added. It is not a self-service setting.
Protect your key
- Treat
X-API-Keyas a deployment secret and rotate it with your normal secret management, or withPOST /v1/keys/{id}/rotate. - Keep
session_idandencryption_keytransient and inside your trusted server. - Never send a password, a one-time code or a private value in a normal call parameter. Use the private-input channels described in Signed-in and action endpoints.