# BlinkPDF auth.md

BlinkPDF renders Markdown into print-ready PDFs for AI agents over the Model
Context Protocol (MCP) at `https://mcp.blinkpdf.io/mcp`. This document tells an agent
how to obtain and present the credential that authorizes a render.

## Who this is for

Autonomous agents — and the people who operate them — that call the BlinkPDF
`render_pdf` MCP tool or the REST render API on a user's behalf.

## How registration works

BlinkPDF supports the OAuth authorization-code + PKCE flow for remote MCP
connectors. The identity model is **user-claimed via a verified email**
(`identity_assertion` / `verified_email`): the user signs in to Blink PDF,
approves the connector on a consent screen, and the BFF issues a user-scoped
bearer token for the `pdf:render` scope. Refresh tokens are issued
only when `offline_access` is authorized and rotate on use.

Manual clients that do not support OAuth can still use **user-scoped API keys**
(`bp_*`), created by a signed-in user in Blink PDF Platform. There is no
anonymous or agent-attested (ID-JAG) registration.

OAuth connector flow:

1. Discover protected resource metadata at
   `https://mcp.blinkpdf.io/.well-known/oauth-protected-resource`.
2. Register a public client at `https://identity.blinkpdf.io/oauth/register`.
3. Send the user through `https://identity.blinkpdf.io/oauth/authorize` with
   `response_type=code`, `code_challenge_method=S256`,
   `resource=https://mcp.blinkpdf.io/mcp`, and `scope=pdf:render offline_access`.
4. The signed-in user must approve the consent screen before the BFF issues a
   code.
5. Exchange the code at `https://identity.blinkpdf.io/oauth/token`.

Manual API-key fallback:

1. **Register** at https://app.blinkpdf.io/register or **sign in** at https://app.blinkpdf.io/login.
2. **Claim a credential** on https://app.blinkpdf.io/api-keys: create an API key and copy the secret
   (shown once).
3. **Store the key** where the agent reads its secrets.

## Presenting the credential

For OAuth connectors, send the BFF-issued access token to MCP:

    Authorization: Bearer <oauth_access_token>

For API-key clients, send the key as a bearer token on MCP or REST requests:

    Authorization: Bearer bp_xxx

`x-api-key: bp_xxx` is accepted as an API-key fallback. A `401` means the
credential is missing, expired, wrong, disabled, or revoked — refresh or replace
the credential, do not retry blindly.

## Revoking the credential

Disconnect the OAuth connector in the client to stop future refreshes. Manual
API keys can be deleted from https://app.blinkpdf.io/api-keys; they stop working immediately.

## Billing

BlinkPDF uses a **human-in-the-loop** subscription model: an agent cannot start
Stripe checkout on its own. When renders hit free-tier limits or return
`402 spend_cap_reached`, the operator upgrades through the account dashboard
while signed in.

1. **Sign in** on Blink PDF Platform (https://app.blinkpdf.io/login).
2. **Upgrade** on https://app.blinkpdf.io/billing — the UI calls the BFF checkout API with the session
   cookie; Stripe opens in the browser. Agents do not receive a checkout URL.
3. **Render with the paid account** — OAuth connectors keep using the MCP
   `render_pdf` tool; API-key clients use `Authorization: Bearer bp_...` on
   `https://api.blinkpdf.io/v1/render` or MCP.

The BFF subscription API (`POST /subscriptions/checkout`, `GET /subscriptions/status`)
is listed under `bff_base_url` in `agent_commerce` for integrators with a session cookie.

Published plan limits (free, pro, business) match enforcement in the REST API.
Machine-readable catalog: `agent_commerce` on the authorization-server metadata
and `https://mcp.blinkpdf.io/.well-known/blinkpdf-commerce.json`.

## Machine-readable discovery

- Protected resource metadata:
  `https://mcp.blinkpdf.io/.well-known/oauth-protected-resource`
- Authorization server metadata:
  `https://identity.blinkpdf.io/.well-known/oauth-authorization-server`
- MCP mirror of authorization server metadata (carries `agent_auth` and
  `agent_commerce`):
  `https://mcp.blinkpdf.io/.well-known/oauth-authorization-server`
- Commerce discovery JSON:
  `https://mcp.blinkpdf.io/.well-known/blinkpdf-commerce.json`
- Render skill:
  `https://mcp.blinkpdf.io/.well-known/agent-skills/render-pdf/SKILL.md`

## Credential summary

| Field | Value |
| --- | --- |
| Credential type | OAuth bearer token for MCP; `api_key` (`bp_*`) fallback |
| Presentation | `Authorization: Bearer` (header) |
| Identity model | user-claimed `verified_email` (no anonymous or ID-JAG) |
| Scope | `pdf:render` |
| Issuer | `https://identity.blinkpdf.io` |
| Revocation | Disconnect OAuth client; API keys: https://app.blinkpdf.io/api-keys |