> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent authentication

> The auth.md agent-onboarding recipe — discovery, the credential decision tree, registration, usage, errors, and revocation — for agents connecting to Particle Pro.

This page mirrors the machine-readable onboarding document served at [`https://api.particle.pro/auth.md`](https://api.particle.pro/auth.md) and [`https://mcp.particle.pro/auth.md`](https://mcp.particle.pro/auth.md), following the [auth.md protocol](https://github.com/workos/auth.md). If you are an agent reading this: the steps below are authoritative and in order.

Particle Pro has 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/`.

And two credential types, 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](https://platform.particle.pro/tokens).

There is **no anonymous agent self-registration**: every credential is tied to a human-owned platform account. The fastest path for a fully headless agent is to ask your operator for an API key.

## Step 1 — Discover

Discovery is two hops.

Fetch the RFC 9728 protected-resource metadata at the resource you want to call:

```http theme={"dark"}
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. Then follow `authorization_servers` to the RFC 8414 Authorization Server metadata:

```http theme={"dark"}
GET https://api.particle.pro/.well-known/oauth-authorization-server
```

The `agent_auth` block in that document is the machine-readable summary of this page — see [Authentication → Agent discovery](/mcp/authentication#agent-discovery) for the full block.

## 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), or bring a client-id metadata document URL (CIMD) as your `client_id`. 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). The user approves and selects a project at platform.particle.pro.
3. **Exchange**: `POST https://api.particle.pro/oauth/token` → access token (15-minute JWT) plus a refresh token (30 days, rotated on every use).

Stock MCP clients run this flow automatically — see the [Quickstart](/mcp/quickstart). Full protocol detail: [Authentication](/mcp/authentication).

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

A human operator:

1. Creates an account at [platform.particle.pro](https://platform.particle.pro) (email verification required).
2. Creates or joins an organization and project.
3. Mints a key at [platform.particle.pro/tokens](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 carry `WWW-Authenticate: Bearer realm="mcp", error="invalid_token", resource_metadata="…"` with a human-readable reason in the body — see [MCP errors](/mcp/errors).
* REST errors are RFC 9457 `application/problem+json` with a stable `error_code`. When self-service resolution is available, a `resolve` object is included telling you (or your operator) how to fix the problem — see the [error catalog](/errors/overview).

## 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](https://platform.particle.pro) — see [Manage connections](/mcp/authentication#manage-connections).
* An API key: a signed-in human revokes it in the [dashboard](https://platform.particle.pro/tokens).
* Access tokens are stateless 15-minute JWTs: revoking the grant stops refresh, and outstanding tokens expire on their own.