Skip to main content
This page mirrors the machine-readable onboarding document served at https://api.particle.pro/auth.md and https://mcp.particle.pro/auth.md, following the auth.md protocol. 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.
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: 
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: 
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 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. Full protocol detail: Authentication.

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

A human operator:
  1. Creates an account at platform.particle.pro (email verification required).
  2. Creates or joins an organization and project.
  3. Mints a key at 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.
  • 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.

​
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 — see Manage connections.
  • An API key: a signed-in human revokes it in the dashboard.
  • Access tokens are stateless 15-minute JWTs: revoking the grant stops refresh, and outstanding tokens expire on their own.