# Particle Pro — 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.

## 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.

## 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 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.

## What is NOT supported

Declared here so you do not waste requests probing:

- **Anonymous registration** — no credential is issued without a human-owned account.
- **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

- 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