Authentication

Every request to the Pagr API is authenticated with a bearer API key. There is no OAuth flow, no token exchange, and no refresh step — the key is a long-lived credential you send on each request.

Getting a key

You generate keys in the workspace under Settings → API Keys. See API Keys for the full walkthrough, including the difference between test and production keys and how to rotate a key that’s been exposed.

The Authorization header

Send your key as a bearer token in the Authorization header:

Authorization: Bearer pagr_prod_xxxxxxxxxxxxxxxx

That’s the only credential a request needs. No other header carries authentication, and there’s no session or cookie to maintain. Every official SDK attaches it for you — you pass the key when constructing the client.

The two service probes (GET /v1/meta/status and GET /v1/meta/version) are the only anonymous endpoints, so an uptime monitor or autoscaler can call them without a credential. Everything else requires the header.

Test vs Production keys

The key’s prefix decides which environment the request runs in — you never pass a separate flag:

	Test (pagr_test_*)	Production (pagr_prod_*)
Output	Watermarked	Full, unwatermarked
Page credit	Not consumed	Consumed
Batch cap	10 documents per request	No fixed cap
Blocks rendering on	Error issues only	Warning and Error issues

Switching environments is just a matter of switching keys — including at runtime, via set_api_key on a live client.

The last row bites people

Production rendering blocks on warnings as well as errors. A payload that renders cleanly with a test key can be rejected with a production key — typically for a MissingBinding, UnresolvedImage or UnresolvedFont issue, all of which are Warning severity. See Validate before rendering.

For how the two environments differ in the output itself, see Renders → Test vs Production.

Keeping your key safe

Your API key grants the ability to render documents and read your organisation’s data, so treat it like a password:

Caution

Never embed a key in client-side code (a browser bundle, a mobile app) or commit it to a public repository. Keep it in an environment variable or a secrets manager, and pass it to your backend at runtime. If a key is ever exposed, generate a replacement and revoke the old one from Settings → API Keys.

Rotation doesn’t require a restart: every SDK exposes set_api_key (or its language equivalent) to swap the key on a live client without tearing down its connection pool. Be aware that swapping a pagr_test_ key for a pagr_prod_ one silently switches every subsequent render to real, credit-consuming output — see Configure the client.

The other direction: authenticating Pagr to you

Your API key authenticates you to Pagr. When Pagr calls you — the webhook callbacks from an async render job — the direction reverses, and so does the mechanism. A callback carries no Authorization header. Instead it’s signed with your organisation’s webhook signing secret, in an X-Pagr-Signature header your receiver verifies.

That secret is a second, separate credential. You’ll find it under Settings → API Keys alongside your API keys, it’s rotatable there, and it is not exposed on the /v1 API — no endpoint returns it and no SDK method fetches it, so copy it into your receiver’s configuration by hand. It is not interchangeable with an API key: you can’t send a whsec_ value as a bearer token, and an API key won’t verify a signature. See Webhooks → Verifying the signature.

401 vs 403

Two different authentication-related errors mean two different things:

• 401 Unauthorized — the key is missing, malformed, or invalid. The request wasn’t authenticated at all. Check that the Authorization header is present and the key is correct. A distinct NotAuthenticated code means the key is well-formed but has no associated organisation.
• 403 Forbidden — the key is valid and the request was authenticated, but the authenticated organisation isn’t allowed to perform this action. A new key won’t fix this — the permission is the issue.

Cross-tenant access returns 404, not 403

Asking for a template, document or render job belonging to another organisation returns 404, not 403 — as far as your key is concerned, the resource doesn’t exist. So a 403 always means your own organisation lacks permission for the action, never that you pointed at someone else’s data.

See Errors for every other status code the API returns, and Handle errors and retries for the exception each maps to in the SDKs.

Related articles

• How the API works — base URL, rendering shapes, and errors.
• Configure the client — where the key goes, and how to rotate it.
• Errors — the full status code reference.
• API Keys — generate, rotate, and manage keys.
• Webhooks — how callbacks are authenticated in the other direction, with a signature rather than a bearer key.
• SDKs — client libraries that handle the header for you.