# auth.md

BlazeDocs supports agent access through user-approved API keys and, when
configured, x402 machine payments. The service host, API host, and resource
server are all `https://blazedocs.io`.

## Agent registration

BlazeDocs publishes machine-readable discovery for automated agent onboarding.

- OAuth Protected Resource Metadata: `https://blazedocs.io/.well-known/oauth-protected-resource`
- OAuth Authorization Server metadata: `https://blazedocs.io/.well-known/oauth-authorization-server`
- OpenID Connect discovery (Clerk): `https://blazedocs.io/.well-known/openid-configuration`
- API catalog (RFC 9727): `https://blazedocs.io/.well-known/api-catalog`
- OpenAPI service description: `https://blazedocs.io/.well-known/openapi.json`
- Agent skills index: `https://blazedocs.io/.well-known/agent-skills/index.json`
- MCP server card: `https://blazedocs.io/.well-known/mcp/server-card.json`

### Registration methods

| Method | Identity | Credential | Register |
| --- | --- | --- | --- |
| BlazeDocs Connect | verified email (browser approval) | API key (`bd_live_...`) | `POST https://blazedocs.io/api/connect/session` |
| Existing dashboard key | verified email | API key | `https://blazedocs.io/dashboard/api` |
| x402 machine payment | anonymous | signed USDC payment | `GET https://blazedocs.io/api/x402/probe` |

BlazeDocs does not expose autonomous OAuth dynamic client registration at this
time. Agents should use BlazeDocs Connect for user-approved API keys or x402
for anonymous URL-based conversion.

## 1. Discover

Use these stable resources before choosing a registration method.

- Agent auth document: `https://blazedocs.io/auth.md`
- OAuth protected resource: `https://blazedocs.io/.well-known/oauth-protected-resource`
- OAuth authorization server: `https://blazedocs.io/.well-known/oauth-authorization-server`
- API catalog: `https://blazedocs.io/.well-known/api-catalog`
- API documentation: `https://blazedocs.io/api-docs`
- Agent workflow page: `https://blazedocs.io/for/ai-agents`
- API key dashboard: `https://blazedocs.io/dashboard/api`
- Connect session endpoint: `https://blazedocs.io/api/connect/session`
- Connect exchange endpoint: `https://blazedocs.io/api/connect/exchange`
- x402 probe endpoint: `https://blazedocs.io/api/x402/probe`
- x402 paid conversion endpoint: `https://blazedocs.io/api/x402/convert`

## 2. Pick a method

Choose the first method that matches what you and the user have available.

- Existing API key: use this when the user already has a `bd_live_...` key.
- BlazeDocs Connect: use this when the user can approve a browser-based key
  grant. This creates a standard BlazeDocs API key for the user's account.
- x402 payment: use this when you only need to convert a public HTTPS PDF URL
  and can pay per request with an x402-capable client.

API keys created through Connect are full BlazeDocs API keys. BlazeDocs does not
currently expose scoped API keys for agents.

## 3. Register with BlazeDocs Connect

Create a pending Connect session, send the user to the returned approval URL,
then exchange the approved session for an API key.

```http
POST https://blazedocs.io/api/connect/session
Content-Type: application/json
```

```json
{
  "provider": "agent-name",
  "keyName": "Agent name",
  "successUrl": "https://agent.example/success",
  "metadata": {
    "agent": "agent-name"
  }
}
```

A successful response includes the session ID and approval URL.

```json
{
  "sessionId": "connect_session_id",
  "approvalUrl": "https://blazedocs.io/connect/connect_session_id",
  "expiresAt": 1780000000000
}
```

Ask the user to open `approvalUrl`, sign in, and approve the key grant. While
waiting, poll the session endpoint.

```http
GET https://blazedocs.io/api/connect/session?sessionId=connect_session_id
```

When the session status is `approved`, exchange it once.

```http
POST https://blazedocs.io/api/connect/exchange
Content-Type: application/json
```

```json
{
  "sessionId": "connect_session_id"
}
```

A successful exchange returns a standard BlazeDocs API key. Store it securely and
do not show it again after setup.

```json
{
  "success": true,
  "key": "bd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "keyPrefix": "bd_live_xxxxxxxx",
  "provider": "agent-name"
}
```

## 4. Use an API key

Pass the key in either supported request header. Prefer the `Authorization`
header unless your HTTP client cannot set it.

```http
Authorization: Bearer bd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```http
x-api-key: bd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Convert a PDF upload with the authenticated HTTP API.

```http
POST https://blazedocs.io/api/v1/convert
Authorization: Bearer bd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: multipart/form-data
```

Use `output_format=markdown` for the default output, or `output_format=html` when
complex tables need browser-native structure.

## 5. Use x402 machine payment

The x402 flow converts public HTTPS PDF URLs without a BlazeDocs account. Probe
first so you know the page count, maximum authorization amount, network, and
paid conversion URL.

```http
GET https://blazedocs.io/api/x402/probe?url=https%3A%2F%2Fexample.com%2Fpaper.pdf&max_pages=10
```

A successful probe response includes `convert_url`, `network`,
`estimated_settlement_price`, and `max_authorization_price`.

```json
{
  "success": true,
  "page_count": 4,
  "network": "eip155:84532",
  "schemes": ["exact", "upto"],
  "estimated_settlement_price": "$0.08",
  "max_authorization_price": "$0.20",
  "max_pages": 10,
  "convert_url": "https://blazedocs.io/api/x402/convert?url=...&max_pages=10&output_format=markdown"
}
```

Request `convert_url` without payment to receive `402 Payment Required`. Read the
`Payment-Required` response header, sign an x402 payment for one of the
advertised requirements, and retry the same URL with `Payment-Signature`.
Legacy clients may send `x-payment` instead. Prefer `exact` when the client
has USDC but no gas token; use `upto` only when the client already has Permit2
allowance or can create it.

```http
GET https://blazedocs.io/api/x402/convert?url=https%3A%2F%2Fexample.com%2Fpaper.pdf&max_pages=10&output_format=markdown
Payment-Signature: <signed-payment-payload>
```

BlazeDocs settles only after OCR succeeds. The `exact` option charges the
`max_pages` authorization amount. The `upto` option is capped by `max_pages`
and can settle the actual PDF page count.

## 6. Errors

Use this table to recover from common errors.

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `missing_url`, `invalid_url`, `unsupported_output_format` | Fix the request and retry. |
| 401 | `UNAUTHORIZED` | Ask the user for a valid API key or restart Connect registration. |
| 403 | Connect session not approved | Keep waiting for user approval or restart registration. |
| 410 | Connect session expired | Create a new Connect session. |
| 413 | `file_too_large`, `page_limit_exceeded` | Use a smaller PDF or lower `max_pages`. |
| 415 | `unsupported_content_type` | Provide a URL that returns a PDF. |
| 422 | `invalid_pdf`, `no_content` | The URL did not produce a usable PDF conversion. |
| 402 | `payment_required`, `payment_settlement_failed` | Complete or retry the x402 payment flow. |
| 503 | `x402_not_configured`, `service_unavailable` | Use API-key auth or retry after BlazeDocs enables the service. |

On any 401 from a previously working API key, discard the key and ask the user
to re-authorize through Connect or the dashboard.