Authentication

How to authenticate with the PodPDF API using API keys or a dashboard session token.

Overview

PodPDF accepts two credentials, and which one you need depends on the endpoint.

API key — for conversions and job lookups:

X-API-Key: your_api_key_here

Cognito ID token — for account, plan and webhook management:

Authorization: Bearer <cognito_id_token>

Endpoint	API key	JWT
POST /quickjob, POST /longjob	✅	✅
POST /bulkjob, POST /bulkjob/upload-url	✅	✅
GET /jobs/{job_id}, /files, /download	✅	✅
GET /me	✅	✅
POST /pdf/merge, /pdf/split, /pdf/inspect, /pdf/upload-url, /pdf/jobs, /pdf/edit, /pdf/edit/preflight	✅	✅
POST /templates/{template_id}/render	✅	✅
/templates (library, create, edit, delete, preview, asset uploads)	❌	✅
GET /jobs (list)	❌	✅
GET /plans, /plans/{plan_id}	❌	✅
/accounts/me/* (account, billing, credits, subscription, API keys, webhooks)	❌	✅
GET /accounts/me/subscription/plans (public, no credentials needed)	✅	✅

API keys are rejected at the gateway on the JWT-only routes. See Plans & Billing for the billing and subscription endpoints. An API key may also be sent as Authorization: Bearer pk_...; if a request carries both a key and a token, the key is used.

Quick Start

1. Get Your API Key - Sign up and copy your API key from the dashboard
2. Use Your Key - Include it in all API requests

How It Works

Conversion requests include your API key in the X-API-Key header:

curl -X POST https://api.podpdf.com/quickjob \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "input_type": "html",
    "html": "<h1>Hello World</h1>"
  }' \
  --output document.pdf

Getting Your API Key

Sign in first

The first key has to come from the dashboard — creating a key requires a signed-in session, so there is no way to bootstrap one with an API key alone.

Step 1: Sign Up

1. Go to https://app.podpdf.com/signup
2. Create your account with email and password, or click Continue with Google
3. Verify your email (not needed with Google)

Dashboard sign-in methods

The dashboard supports email and password or Google sign-in. If you already have an email account, signing in with Google using the same verified email links to that account. API keys and Cognito ID tokens work the same no matter which method you use to sign in, so no API or integration changes are needed.

Step 2: Get Your API Key from Dashboard

1. Sign in to https://app.podpdf.com
2. Navigate to the API Keys section
3. Copy your API key (it will be shown only once)

Save Your Key

API keys are only displayed once when created. Save it securely immediately. If you lose it, you'll need to generate a new one.

Keep It Secret

Your API key is like a password. Never share it publicly or commit it to version control.

Using Your API Key

Include your API key in the X-API-Key header on every conversion and job request:

cURL Example

curl -X POST https://api.podpdf.com/quickjob \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input_type":"html","html":"<h1>Test</h1>"}' \
  --output test.pdf

JavaScript Example

const fetch = require('node-fetch');

async function generatePDF() {
  const response = await fetch('https://api.podpdf.com/quickjob', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      input_type: 'html',
      html: '<h1>Hello World</h1>'
    })
  });

  const buffer = await response.buffer();
  // Save or process the PDF
}

Python Example

import requests

def generate_pdf():
    response = requests.post(
        'https://api.podpdf.com/quickjob',
        headers={
            'X-API-Key': 'your_api_key_here',
            'Content-Type': 'application/json'
        },
        json={
            'input_type': 'html',
            'html': '<h1>Hello World</h1>'
        }
    )
    
    if response.status_code == 200:
        with open('output.pdf', 'wb') as f:
            f.write(response.content)

Security Best Practices

✅ DO:

• Store securely - Use environment variables or secret management
• Use HTTPS - Always make requests over HTTPS
• Rotate regularly - Generate new keys periodically
• Monitor usage - Check your dashboard for unusual activity
• Use different keys - Separate keys for development and production

❌ DON'T:

• Commit to git - Never commit API keys to source control
• Share publicly - Don't post keys in forums or documentation
• Hardcode - Don't hardcode keys in your application
• Use in client-side code - Never expose keys in frontend JavaScript

Managing API Keys

Keys can be managed from the dashboard or over the API. The management endpoints are JWT-only — they accept a Cognito ID token and reject API keys, so a key can never create or revoke another key:

Method	Path	Purpose
POST	/accounts/me/api-keys	Create a key (the plaintext key is returned once)
GET	/accounts/me/api-keys	List keys (prefix and metadata only)
DELETE	/accounts/me/api-keys/{api_key_id}	Revoke a key

Viewing Your Keys

Access your API keys from the dashboard:

1. Sign in to https://app.podpdf.com
2. Go to Settings → API Keys
3. View all your active keys

Creating New Keys

You can create multiple API keys for different environments (e.g., development, production):

1. Sign in to the dashboard
2. Go to Settings → API Keys
3. Click Create New Key
4. Give it a descriptive name (e.g., "Production" or "Development")
5. Copy and save the key securely

One-Time Display

API keys are only shown once when created. If you lose it, you'll need to generate a new one from the dashboard.

Revoking Keys

If a key is compromised or no longer needed:

1. Sign in to the dashboard
2. Go to Settings → API Keys
3. Find the key you want to revoke
4. Click Revoke or Delete
5. Generate a new key from the dashboard if needed

Environment Variables

Recommended Setup

Store your API key in environment variables:

Linux/Mac (.bashrc or .zshrc):

export PODPDF_API_KEY="your_api_key_here"

Windows (Command Prompt):

set PODPDF_API_KEY=your_api_key_here

Node.js (.env file):

PODPDF_API_KEY=your_api_key_here

Then use in your code:

const apiKey = process.env.PODPDF_API_KEY;

fetch('https://api.podpdf.com/quickjob', {
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  }
});

Common Errors

401 Unauthorized

API key is missing or invalid.

Solution:

• Check that you're including the X-API-Key header
• Verify your API key is correct
• Generate a new key if needed

402 Payment Required

UPGRADE_REQUIRED — the account has no paid plan yet. Buy a credit pack or start a monthly subscription in the dashboard to activate it.

403 Forbidden

Account state, plan, allowance or credit problem. The body's error.code says which:

• ACCOUNT_NOT_FOUND — the key is valid but the account record is missing
• INSUFFICIENT_CREDITS — your subscription allowance, free credits and one-off credits together cannot cover another PDF; buy a credit pack or upgrade your plan in the dashboard
• CONVERSION_TYPE_NOT_ENABLED — that input type is not enabled for your plan
• RATE_LIMIT_EXCEEDED — your plan sets a per-minute limit and you hit it. The standard paid plan sets none. Note that this is a 403, not a 429.

429 Too Many Requests

Platform throttling from API Gateway, which is shared across accounts and is not your plan's limit. Back off and retry with jitter.

Testing Your API Key

Quick test to verify your API key works:

curl -X POST https://api.podpdf.com/quickjob \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "input_type": "html",
    "html": "<h1>Test</h1><p>If you can read this, your API key works!</p>"
  }' \
  --output test.pdf

If successful, you'll get a test.pdf file.

Rate Limits

PodPDF charges per PDF, not by rate: each successful PDF costs $0.01, taken from your monthly subscription allowance first and then from your credits (see Plans & Billing). The standard paid plan sets no per-account rate limit, so there is no per-minute cap to plan around. Two things still bound throughput:

• API Gateway's shared platform throttle, which surfaces as 429
• Bulk jobs, where each account may have 2 jobs in flight at a time

A plan that does define rate_limit_per_minute returns 403 RATE_LIMIT_EXCEEDED when it is exceeded. See Limits for the full list.

Need Help?

Lost your API key?
Generate a new one from the dashboard: Settings → API Keys → Create New Key

API key not working?

• Verify you're using the correct key
• Check that it hasn't been revoked
• Make sure you're using the X-API-Key header

Next Steps

• Generate Your First PDF →
• View API Reference →
• See Code Examples →
• Error Handling Guide →