# Particle Pro auth.md — Agent Authentication

You are an agent. This file is the authoritative recipe for obtaining and using credentials for Particle Pro's two protected surfaces:

- **MCP** at `https://mcp.particle.pro` — the Model Context Protocol server (podcast intelligence, companies, people, topics).
- **REST API** at `https://api.particle.pro` — the same data over plain HTTP under `/v1/`.

Two credential types exist, matched to two kinds of callers:

- **OAuth 2.1 access tokens** — for interactive MCP clients (Claude Code, Cursor, ChatGPT, Claude Desktop). Short-lived JWTs, audience-bound to `https://mcp.particle.pro`. A human approves the connection once in a browser.
- **`pp_*` platform API keys** — for headless agents and all REST API calls. Minted by a human in the platform dashboard.

There is **no anonymous agent self-registration**: every credential is tied to a human-owned platform account (the API is paid). The fastest path for a fully headless agent is to ask your operator for an API key from https://platform.particle.pro/tokens. An agent with no operator at all can still call the API by paying per request with x402 — no credential is issued; each request pays for itself (Step 4b).

## Step 1 — Discover

Discovery is two hops; you may have already done this.

### 1a. Protected resource metadata (RFC 9728)

```http
GET https://mcp.particle.pro/.well-known/oauth-protected-resource
GET https://api.particle.pro/.well-known/oauth-protected-resource
```

A 401 from the MCP server also carries a `WWW-Authenticate: Bearer resource_metadata="…"` header pointing at the first document.

### 1b. Authorization server metadata (RFC 8414)

```http
GET https://api.particle.pro/.well-known/oauth-authorization-server
```

The `agent_auth` block in that document is the machine-readable summary of this file.

## Step 2 — Pick a method

1. **A human is present to approve the connection, and you speak MCP** → OAuth 2.1 (Step 3).
2. **You are headless, or you call the REST API** → `pp_*` API key (Step 4). OAuth access tokens are **not** accepted by the REST API — they are audience-bound to the MCP resource.
3. **No human at all, and you hold a wallet with USDC on Base** → pay per request with x402 (Step 4b). Nothing to register, nothing to store.

## Step 3 — OAuth 2.1 (interactive MCP clients)

1. **Register a client**: `POST https://api.particle.pro/oauth/register` (RFC 7591 dynamic client registration; public clients use `"token_endpoint_auth_method": "none"`). Alternatively, skip registration by using an `https://` client-id metadata document URL as your `client_id` (CIMD). Registering a client does **not** issue a credential — a human must still approve.
2. **Authorize**: `GET https://api.particle.pro/oauth/authorize` with `response_type=code`, PKCE `code_challenge_method=S256` (mandatory), and `resource=https://mcp.particle.pro` (mandatory, RFC 8707). The user approves the connection and selects a project at https://platform.particle.pro/oauth/consent.
3. **Exchange**: `POST https://api.particle.pro/oauth/token` → access token (15-minute JWT, `aud=https://mcp.particle.pro`) plus a refresh token (30 days, rotated on every use).

Stock MCP clients run this flow automatically — see https://docs.particle.pro/mcp/quickstart.

## Step 4 — API key (headless agents and the REST API)

A human operator:

1. Creates an account at https://platform.particle.pro (email verification required).
2. Creates or joins an organization and project.
3. Mints a key at https://platform.particle.pro/tokens. The full `pp_…` key is shown exactly once.

Key management is a signed-in human action in the dashboard — a `pp_*` key cannot mint, roll, or revoke credentials, including itself.

## Step 4b — Pay per request (x402, no account)

Send the request with **no credential**. A billable endpoint answers `402 Payment Required` with the x402 payment terms in the `PAYMENT-REQUIRED` header (base64 JSON: network `eip155:8453`, the USDC asset, the amount in atomic units, the recipient) and a `payment_required` body. Sign an EIP-3009 USDC transfer for exactly that amount and repeat the identical request with the payment in the `PAYMENT-SIGNATURE` header; the response carries a `PAYMENT-RESPONSE` receipt. Every price is a whole number of cents from $0.01 per call, listed per endpoint and per MCP tool at https://api.particle.pro/llms.txt (each MCP `tools/call` costs its tool's price; `initialize` and `tools/list` are free); a request that fails is never charged. Alerts and Enterprise-only surfaces are not payable per request. Discovery: `/.well-known/x402` on the API and MCP hosts lists the payable endpoints and terms, and every payable operation in `/openapi.json` carries `x-payment-info`. Full detail: https://docs.particle.pro/x402

## Step 5 — Use the credential

- **MCP**: `Authorization: Bearer <access-token or pp_* key>` or `X-API-Key: pp_…` on every request to `https://mcp.particle.pro`.
- **REST**: `X-API-Key: pp_…` or `Authorization: Bearer pp_…` (or an `api-key` query parameter) on the `https://api.particle.pro/v1/…` data endpoints.
- **Pay per request**: no credential header at all — any presented credential, even an invalid one, takes the credential path and is never challenged for payment.

## What is NOT supported

Declared here so you do not waste requests probing:

- **Anonymous registration** — no credential is issued without a human-owned account. Keyless access exists only as per-request x402 payment (Step 4b), which mints nothing.
- **Identity assertion / ID-JAG** — no RFC 7523 assertion exchange.
- **Device authorization grant** — no RFC 8628 device flow; headless means API key.
- **OTP claim ceremony** — the consent screen in Step 3 is the approval step.
- **OAuth tokens on the REST API** — access tokens are MCP-audience only.

## Errors

- MCP 401s: `WWW-Authenticate: Bearer realm="mcp", error="invalid_token", resource_metadata="https://mcp.particle.pro/.well-known/oauth-protected-resource"` with a human-readable reason in the body.
- REST errors are RFC 9457 `application/problem+json` with a stable machine-readable `error_code`. When self-service resolution is available, a `resolve` object is included telling you (or your operator) how to fix the problem — e.g. `{"action": "create_api_key", "url": "https://platform.particle.pro/tokens"}`.

## Revocation

- Refresh token (revokes its whole grant chain): `POST https://api.particle.pro/oauth/revoke` (RFC 7009).
- An OAuth connection (grant): a signed-in human revokes it under Connected Applications on https://platform.particle.pro.
- An API key: a signed-in human revokes it at https://platform.particle.pro/tokens.
- Access tokens are stateless 15-minute JWTs: revoking the grant stops refresh, and outstanding tokens expire on their own.

## More

- Setup playbook for connecting a client and running a first query: https://api.particle.pro/agents.md
- Endpoint and tool map with per-call prices: https://api.particle.pro/llms.txt
- Human documentation: https://docs.particle.pro/mcp/authentication
- MCP quickstart: https://docs.particle.pro/mcp/quickstart
- This file: https://api.particle.pro/auth.md and https://mcp.particle.pro/auth.md