Authentication

API keys

Every request to the Paperbase API must include an API key in the Authorization header as a Bearer token:

Authorization: Bearer pb_live_…

Keys are issued per-workspace. You get your first key automatically when you sign up at paperbase.dev.

Key types

Paperbase issues two kinds of keys:

Prefix	Type	Use
`pb_live_`	Live key	Production traffic — counts against your monthly quota
`pb_test_`	Test key	Development and CI — renders work identically, does not count against quota. Expires after 24 hours

Get a test key without signing up:

curl -X POST https://api.paperbase.dev/v1/keys/test

Response:

{
  "key": "pb_test_…",
  "expires_at": "2026-07-02T12:00:00Z"
}

Setting the key

Environment variable (recommended)

PAPERBASE_API_KEY=pb_live_…

paperbase.ts

import { Paperbase } from "paperbase";
 
const paperbase = new Paperbase({ apiKey: process.env.PAPERBASE_API_KEY! });

Direct instantiation

const paperbase = new Paperbase({ apiKey: "pb_live_…" });

Raw fetch

const res = await fetch("https://api.paperbase.dev/v1/pdf/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pb_live_…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: { type: "markdown", content: "# Hello" }, template: "report" }),
});

Monthly quota

Tier	Renders/month
Free	100
Starter	500
Builder	2,500
Pro	10,000
Scale	Unlimited

When the quota is exhausted, the API returns 429 PB_MONTHLY_QUOTA_EXCEEDED. The workspace owner must upgrade at paperbase.dev/billing — the limit resets on the first of each month.

401 errors

A 401 means authentication failed before rendering was attempted. The response body always includes a machine-readable agent_message:

{
  "error": {
    "code": "PB_INVALID_API_KEY",
    "type": "authentication_error",
    "human_message": "The API key provided is invalid or expired.",
    "agent_message": "Obtain a valid API key from https://paperbase.dev/dashboard or call POST /v1/keys/test for a free 24-hour test key. Set it as the Bearer token in the Authorization header.",
    "docs_url": "https://paperbase.dev/docs/errors/PB_INVALID_API_KEY",
    "retryable": false,
    "request_id": "req_01HZXYZ"
  }
}

Common causes:

Symptom	Fix
No `Authorization` header	Add `Authorization: Bearer pb_live_…`
Wrong prefix (`Bearer` missing)	Ensure the value is `Bearer <key>`, not just `<key>`
Key starts with `pk_` or similar	Use only `pb_live_` or `pb_test_` keys
Test key expired	Call `POST /v1/keys/test` to get a fresh one
Key not found in DB	Regenerate from the dashboard

Creating additional keys

curl -X POST https://api.paperbase.dev/v1/keys \
  -H "Authorization: Bearer pb_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production worker", "type": "live" }'

The key field is returned once only — store it in a secret manager (e.g. Vercel Environment Variables, AWS Secrets Manager) immediately.

Errors & warnings — full error code reference
API reference — complete request/response schema

On this page