# SeenPDF auth.md

Agent registration and authentication guide for the SeenPDF document platform.

## Audience

This document is for **AI agents** that need to authenticate with SeenPDF to upload, convert, and share PDF documents on behalf of users.

## Protected Resource Metadata

```
GET https://seenpdf.com/.well-known/oauth-protected-resource
```

| Field | Value |
|-------|-------|
| resource | `https://seenpdf.com` |
| authorization_servers | `https://api.seenpdf.com` |
| bearer_methods_supported | `header` |
| scopes_supported | `openid`, `email`, `profile`, `documents:read`, `documents:write` |

## Authorization Server

```
GET https://api.seenpdf.com/.well-known/oauth-authorization-server
```

Issuer: `https://api.seenpdf.com`

## Registration Methods

### 1. Google OAuth (interactive)

For agents acting on behalf of a human user with browser interaction:

1. Redirect user to `GET https://api.seenpdf.com/auth/google`
2. After callback, use session cookie or `Authorization: Bearer {session_id}`
3. Access protected endpoints at `https://api.seenpdf.com/api/*`

### 2. x402 Anonymous (autonomous agents) {#anonymous}

For fully autonomous AI agents without human interaction:

1. `POST https://api.seenpdf.com/api/documents/upload` without auth
2. Receive `402 Payment Required` with x402 payment details
3. Pay 1.00 USD equivalent (USDC/USDT) on Solana, Base, Polygon, or Arbitrum
4. Resubmit with `Authorization: x402 {transaction_id}`

Credential type: `x402` transaction proof (min 32-char transaction ID).

### 3. Session Bearer (after OAuth)

```
Authorization: Bearer {session_id}
```

Obtain `session_id` from OAuth callback redirect query parameter or `/api/me`.

## Discovery

| Resource | URL |
|----------|-----|
| Agent Card (A2A) | `https://seenpdf.com/.well-known/agent-card.json` |
| API Catalog | `https://seenpdf.com/.well-known/api-catalog` |
| OpenAPI Spec | `https://seenpdf.com/openapi.yaml` |
| Agent Skills | `https://seenpdf.com/.well-known/agent-skills/index.json` |
| LLM Docs | `https://seenpdf.com/llms-full.txt` |

## Scopes

| Scope | Description |
|-------|-------------|
| `documents:read` | Read document metadata and PDF content |
| `documents:write` | Upload, update, and delete documents |
| `openid`, `email`, `profile` | Standard OAuth user identity |

## Support

- Documentation: https://seenpdf.com/llms-full.txt
- Health check: https://api.seenpdf.com/api/health