pdf-mcp supports two authentication methods: API Keys for simple integrations and OAuth 2.0 for MCP-compliant AI agent integrations.

API Key Authentication

API keys are the simplest way to authenticate with pdf-mcp. They’re ideal for server-side applications, automation workflows, and direct API integrations.

Creating an API Key

1. Sign in to your dashboard at app.pdf-mcp.io
2. Navigate to API Keys in the sidebar
3. Click Generate New Key
4. Give your key a descriptive name (e.g., “Production Server”, “n8n Workflow”)
5. Copy the key immediately - you won’t be able to see it again

Using API Keys

Include your API key in the Authorization header of every request:

curl -X POST https://api.pdf-mcp.io/htmlToPdf \
  -H "Authorization: Bearer pdfmcp_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}'

API Key Best Practices

• Never expose keys in client-side code - API keys should only be used server-side
• Use separate keys for different environments - Create separate keys for development, staging, and production
• Rotate keys regularly - Generate new keys periodically and revoke old ones
• Use descriptive names - Name keys after their purpose for easy management

Key Prefixes

All pdf-mcp API keys use prefixes for easy identification:

Revoking Keys

If a key is compromised:

1. Go to API Keys in your dashboard
2. Find the compromised key
3. Click Revoke
4. Generate a new key and update your applications

Revoked keys are immediately invalid - all requests using them will fail.

OAuth 2.0 Authentication

OAuth 2.0 is required for MCP (Model Context Protocol) server integrations. This allows AI agents like Claude to securely access pdf-mcp on behalf of users.

Creating an OAuth Application

1. Sign in to your dashboard
2. Navigate to OAuth Apps
3. Click Create New App
4. Configure your application:
   • Name: Display name for users
   • Redirect URIs: Allowed callback URLs
5. Save your client_id and client_secret

OAuth Flow

pdf-mcp implements the standard OAuth 2.0 Authorization Code flow:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  AI Agent   │────►│  pdf-mcp    │────►│    User     │
│  (Client)   │     │  (Auth)     │     │  (Consent)  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │  1. Auth Request  │                   │
       │──────────────────►│                   │
       │                   │  2. Login/Consent │
       │                   │◄─────────────────►│
       │  3. Auth Code     │                   │
       │◄──────────────────│                   │
       │                   │                   │
       │  4. Exchange Code │                   │
       │──────────────────►│                   │
       │  5. Access Token  │                   │
       │◄──────────────────│                   │
       │                   │                   │
       │  6. API Request   │                   │
       │──────────────────►│                   │
       │  7. PDF Response  │                   │
       │◄──────────────────│                   │
└──────┴──────────────────┴───────────────────┘

Step 1: Authorization Request

Redirect users to the authorization endpoint:

https://api.pdf-mcp.io/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  response_type=code&
  scope=pdf:generate pdf:read&
  state=random_state_string

Parameters:

Step 2: Token Exchange

After user consent, exchange the authorization code for tokens:

curl -X POST https://api.pdf-mcp.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://your-app.com/callback"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZn...",
  "scope": "pdf:generate pdf:read"
}

Step 3: Using Access Tokens

Use the access token exactly like an API key:

curl -X POST https://api.pdf-mcp.io/htmlToPdf \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>"}'

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get new tokens:

curl -X POST https://api.pdf-mcp.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=dGhpcyBpcyBhIHJlZn..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

OAuth Scopes

Request only the scopes your application needs.

MCP Server Configuration

For AI agents using MCP, configure the server with:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "npx",
      "args": ["-y", "@pdf-mcp/server"],
      "env": {
        "PDF_MCP_CLIENT_ID": "your_client_id",
        "PDF_MCP_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

The MCP server handles OAuth automatically, prompting users for authorization when needed.

Security Recommendations

For API Keys

• Store keys in environment variables, never in code
• Use secrets management in CI/CD pipelines
• Monitor key usage in your dashboard
• Revoke unused keys promptly

For OAuth Apps

• Keep client_secret confidential
• Validate the state parameter to prevent CSRF
• Use HTTPS for all redirect URIs
• Implement token refresh before expiration
• Request minimal scopes needed

Rate Limiting

Authentication failures are rate-limited:

• 5 failed attempts: 1-minute cooldown
• 10 failed attempts: 15-minute cooldown
• 20 failed attempts: Account review required

Troubleshooting

”Invalid API Key” Error

• Verify the key hasn’t been revoked
• Check for extra whitespace or characters
• Ensure you’re using the correct environment (live vs test)

“Invalid Grant” OAuth Error

• Authorization codes expire in 10 minutes
• Each code can only be used once
• Ensure redirect_uri matches exactly

”Insufficient Scope” Error

• Your token doesn’t have required permissions
• Request additional scopes during authorization