Concepts
Choose credentials by route family
This API intentionally uses three auth models: API keys for rendering routes, hybrid bearer auth for signed in account routes, and signed links for specific public confirmation flows.
API key routes
Rendering routes require the render API key header, including single render and batch workflows.
Hybrid account routes
Account routes use an in memory bearer access token plus an httpOnly refresh cookie, including profile, subscriptions, billing actions, and API key lifecycle.
Public signed link flows
A small set of actions uses signed tokens in links so a user can safely confirm one action without a login session.
Comparison
Map the route, then send the matching credential
Most auth errors come from using the wrong credential type on the right endpoint. Classifying the route family first avoids that.
Auth comparison matrix
API key
Header: X-API-Key
Use for queued rendering routes such as single render, accepted job status, and batch create.
POST/v1/pdf
GET/v1/pdf/jobs/:id
POST/v1/pdf/batch
Hybrid bearer auth
Authorization header + httpOnly refresh cookie
Use for account routes such as profile reads, subscription views, and API key management under the user surface. Keep the access token in memory and use the refresh cookie only to rotate it.
GET/user/profile
GET/user/subscription
Public signed link
Signed token in query or body
Use for scoped public confirmation routes that are intentionally accessed through a signed link rather than a login session.
GET/public/auto-overage/disable
POST/public/auto-overage/disable
Route Families
Each route family has one trust model
Keep this split in mind as you move between rendering, account, and public confirmation flows.
API key routes
Rendering routes use machine auth
Render creation and status or download routes rely on the render API key header rather than user bearer tokens.
POST/v1/pdf
POST/v1/pdf/batch
Hybrid bearer routes
Account routes use user auth
Identity, profile, subscription, billing actions, and API key lifecycle routes act on a signed in user through an in memory bearer access token that is refreshed with an httpOnly cookie.
GET/user/profile
GET/user/subscription
Public signed link flows
Some confirmation actions are intentionally public
These routes do not accept bearer or API keys. Trust comes from a temporary signed token sent in the link.
GET/public/auto-overage/disable
Common Mistakes
Credential mismatch is more common than bad credentials
A valid key or token can still fail when the route expects a different auth model.
- Do not send bearer tokens to the rendering surface, including /v1/pdf, /v1/pdf/jobs/:id, or /v1/pdf/batch. Those routes require the render API key header.
- Do not send API keys to /user account routes such as profile, billing, and API key lifecycle operations.
- Do not persist access tokens in localStorage or sessionStorage. Keep bearer access tokens in memory and rely on the refresh cookie to rehydrate the session.
- Do not treat signed link routes as reusable API endpoints. They are scoped confirmation flows with token expiry.
- Do not treat internal webhook routes as public API endpoints. They are service to service integrations handled by the platform, not by API consumers.
Choose The Right Credential
Use this quick decision rule for every new call
Decide what the route is doing first. Then send the credential model that route family expects.
01
Is this route creating or tracking render work?
Use the render API key header for single render, render jobs, and batch endpoints.
02
Is this route acting on a user account?
Use hybrid bearer auth for identity, profile, subscription, billing, templates, and key-management flows: access token in memory, refresh token in the httpOnly cookie.
03
Did this route come from a signed email link?
Use the signed link token flow exactly as documented for that public confirmation route.
Next Steps
Go to reference pages for exact contracts
This concept page explains the model. Use these routes when you need headers, fields, and exact status behavior.
Need signed in route details?
Open authentication reference
Use this page for the hybrid auth contract across login, token lifecycle, refresh, and account profile flows.
Need API key lifecycle details?
Open API keys reference
Create, rotate, allowlist, and revoke the credentials used on rendering route families.
Need rendering request contracts?
Open single render reference
Use this page for required headers, input modes, output modes, and success-path behavior.