# Authenticating to Pipecorn

You are an agent. Pipecorn has two surfaces, the MCP server and the REST API. The MCP server accepts OAuth 2.1 or an API key. The REST API and the CLI accept an API key. A person with a Pipecorn account authorizes every agent: Pipecorn's authorization server publishes no `agent_auth` block, so there is no `identity_endpoint`, and `identity_assertion` (ID-JAG), `service_auth` and anonymous registration are not supported.

## 1. Discover

An unauthenticated call to the MCP server answers `401` with a `WWW-Authenticate` header that names the protected resource metadata:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="https://mcp.pipecorn.com", resource_metadata="https://mcp.pipecorn.com/.well-known/oauth-protected-resource"
```

Fetch it, then the authorization server metadata at https://mcp.pipecorn.com/.well-known/oauth-authorization-server. It lists:

- `authorization_endpoint`: https://mcp.pipecorn.com/oauth/authorize
- `token_endpoint`: https://mcp.pipecorn.com/oauth/token
- `revocation_endpoint`: https://mcp.pipecorn.com/oauth/revoke
- `registration_endpoint`: https://mcp.pipecorn.com/register
- `grant_types_supported`: `authorization_code`, `refresh_token`
- `code_challenge_methods_supported`: `S256`

The REST API has no OAuth. Its OpenAPI spec (https://pipecorn.com/openapi.json) declares one security scheme, an API key in the `X-API-KEY` header.

## 2. Pick a method

| You are | Use |
| --- | --- |
| An MCP client that runs the OAuth flow (Claude, ChatGPT) | OAuth 2.1 on the MCP server |
| An MCP client that sends custom headers (Claude Code, Cursor, `mcp-remote`) | The API key in an `X-API-Key` header |
| Backend code or a workflow tool (Zapier, Make, n8n) | The REST API with the API key in `X-API-KEY` |
| A shell script or CI job | The CLI with the key in `PIPECORN_API_KEY` |

Header names are case-insensitive, so `X-API-Key` and `X-API-KEY` are the same header.

## 3. Register

- OAuth: register your client with dynamic client registration (RFC 7591) at `https://mcp.pipecorn.com/register`.
- API key: the person you work for needs a Pipecorn account (https://app.pipecorn.com/register, the free plan needs no card). They create a key at https://app.pipecorn.com/settings/apis/keys and give it to you. You can't create an account or a key on their behalf.

## 4. Claim

There is no separate claim ceremony. With OAuth, the person signs in and approves your client in the browser at the authorization endpoint, using the authorization code flow with PKCE (`S256`). With an API key, handing you the key is the approval. Treat the key as a secret: never print it, log it or put it in a URL.

## 5. Exchange

Exchange the authorization code at the token endpoint:

```http
POST /oauth/token
Host: mcp.pipecorn.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>&client_id=<client_id>&code_verifier=<verifier>
```

When the access token expires, use the `refresh_token` grant at the same endpoint. An API key needs no exchange.

## 6. Use the access_token

- MCP with OAuth: `Authorization: Bearer <access_token>` on `https://mcp.pipecorn.com/mcp`
- MCP with a key: `X-API-Key: <key>` on `https://mcp.pipecorn.com/mcp`
- REST: `X-API-KEY: <key>` on https://app.pipecorn.com/api/v2
- CLI: `PIPECORN_API_KEY=<key> pipecorn …`, or `~/.config/pipecorn/credentials.json` (mode 0600)

Rate limits are counted per user, not per key.

## Errors

| Response | Meaning | What to do |
| --- | --- | --- |
| `401` | Missing, invalid or expired key or token | Refresh the OAuth token once. If it fails again, ask the person to re-authorize or check the key. |
| `402` with `code: "insufficient_credits"` | The credit balance is empty | Show the person the `top_up_url` from the response and stop. Don't retry. |
| `403` with `code: "workspace_limit_exceeded"` | A workspace admin capped this member's weekly credits | Stop and tell the person to ask their admin. Buying credits won't help. |
| `403` with any other body | The key has no access to this endpoint | Use a key with the right permissions. |
| `422` with `"Plan limit reached."` | A daily or monthly extraction quota ran out | Wait for the reset or upgrade the plan. Credits won't help. |
| `429` | Too many requests | Back off and retry. |

Retry 5xx with exponential backoff. Don't retry a 4xx with the same request. Every code is documented at https://docs.pipecorn.com/api-reference/errors.

## Revocation

- OAuth: POST the token to `https://mcp.pipecorn.com/oauth/revoke` (RFC 7009) with `token=<token>`.
- API key: the person deletes it at https://app.pipecorn.com/settings/apis/keys. Every call made with it then answers `401`.