Authentication

How API keys work, how to send them, how to rotate them safely, and what every auth-related response header means.

Authentication

gpdf-api uses a single auth method for production traffic: a static API key, sent on every request.

Authorization: Bearer gpdf_a1b2c3d4e5f6g7h8...

That's it. No OAuth dance, no signed-URL handshake, no IP allow-list. The same key works against https://api.gpdf.dev and against a self-hosted gpdf-api binary configured with the same secret.

Key shape

Field Format Example
Prefix (13 chars, public) gpdf_[0-9a-f]{8} gpdf_a1b2c3d4
Suffix (24 chars, secret) [0-9a-f]{24} e5f6a7b8…
Full key (raw) gpdf_[0-9a-f]{32} gpdf_a1b2c3d4e5f6a7b8…
  • The prefix is what we show in the dashboard, in logs (api_key_prefix), and in webhook bodies. It's safe to put in error messages.
  • The suffix is the secret. We hash the full key with SHA-256 (with a server-side pepper) and only store the hash. We can't show you the raw key again after creation.

Sending the key

Always use the Authorization: Bearer <key> header. We don't accept query-string keys (?api_key=...) — that prevents the secret leaking into proxy logs and browser history.

curl

curl https://api.gpdf.dev/v1/pdf \
  -H "Authorization: Bearer $GPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d @template.json

Node

await fetch('https://api.gpdf.dev/v1/pdf', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPDF_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body
})

Go

req.Header.Set("Authorization", "Bearer "+os.Getenv("GPDF_API_KEY"))

Multiple keys per account

Most teams want at least two keys: one for production, one for staging. There's no hard cap on key count today — create as many as you need (the dashboard suggests 3 for Free and ~20 for Pro as a guideline, but it's not enforced server-side).

Each key has its own last_used_at, its own logs in the dashboard, and its own quota counter contribution. Quota is per account, not per key — so spreading load across keys doesn't help.

You manage keys at /app/keys, or programmatically with the account endpoints.

Rotating a key

The recommended dance for zero-downtime rotation:

  1. Create a new key (POST /v1/account/keys). You'll see the raw key once — store it.
  2. Roll the new key out to your service (env var, secrets manager, deploy).
  3. Wait for the new key to be exercised — verify in the dashboard's Logs view that you can see calls from the new prefix.
  4. Revoke the old key (DELETE /v1/account/keys/{prefix}).

Once revoked, the old key returns 401 unauthorized immediately. There is no grace period — that is intentional.

What about the dashboard?

Browser-based dashboard requests authenticate with a Firebase ID token, not an API key. You only need to think about that if you're building your own UI on top of the dashboard endpoints — see Account & keys →.

For programmatic backend use, always use API keys.

Every successful render returns headers reflecting your auth context:

Header Example Meaning
X-GPDF-Quota-Limit 10000 Plan + addon limit for this billing period.
X-GPDF-Quota-Remaining 8749 Successful renders you have left.
X-GPDF-Quota-Reset 2026-05-01T00:00:00Z RFC 3339 timestamp of the next reset.
X-GPDF-RateLimit-Limit 40 Burst capacity of the per-key token bucket.
X-GPDF-RateLimit-Remaining 37 Tokens left right now.
X-GPDF-RateLimit-Reset 1714234567 Unix timestamp when the next token arrives.

Use X-GPDF-Quota-Remaining to drive a cheap "you're approaching your quota" UI without any extra requests.

Auth errors

HTTP code When What to do
401 unauthorized Header missing, malformed, or key revoked. Re-issue the key.
403 forbidden Key is valid but doesn't have access to this resource. Check the key's scope — license keys can't call /v1/pdf.
402 quota_exceeded Auth was fine; you ran out of credits. Buy an addon, upgrade, or wait for reset.
429 rate_limited Auth was fine; too many requests too fast. Honour Retry-After.

Full catalog: Errors →.

Storing keys safely

A few points that bite people in production:

  • Never commit a raw key. Even a revoked key shouldn't be in git history. Pre-commit hooks like gitleaks catch the gpdf_ prefix.
  • Use a secrets manager. Cloud Run + Secret Manager, AWS Parameter Store, Vault, Doppler — pick one. Env vars only travel as far as the platform you set them on.
  • Don't share keys across customers. If you're a multi-tenant app, you don't need a per-tenant gpdf-api key — usage is on you, not them — but tag requests with a slug so you can attribute usage internally.

Self-host: license keys instead

If you run gpdf-api yourself, you don't need API keys to authenticate to your instance — your instance is yours. You do need a license key (gpdfl_…) for the binary itself, which is verified once on container start and refreshed daily. See Self-host →.

What's next

Something unclear or missing on this page?