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:
- Create a new key (
POST /v1/account/keys). You'll see the raw key once — store it. - Roll the new key out to your service (env var, secrets manager, deploy).
- Wait for the new key to be exercised — verify in the dashboard's Logs view that you can see calls from the new prefix.
- 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.
Auth-related response headers
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
gitleakscatch thegpdf_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
slugso 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
- POST /v1/pdf → — the render endpoint, with auth examples.
- Account & keys → — programmatic key management.
- Rate limits → — how the per-key buckets work.
- Errors → — every auth error and its fix.
Something unclear or missing on this page?