Authentication and keys
How API keys authenticate requests, and how test keys and live keys differ in watermark, usage, limits and storage.
On this page
Sending your key
Every request to /v1 must carry an API key in the Authorization header:
Authorization: Bearer cpdf_live_0123456789abcdefghijABCDEFGHIJ01A request without a valid key gets 401 with the code invalid_api_key: the header is missing, it is not of the form Bearer <key>, the key does not exist, or it was revoked. The only /v1 path that needs no key is the signed download link of a stored PDF.
Keys look like cpdf_live_ or cpdf_test_ followed by 32 letters and digits. Create and revoke them in the dashboard under API keys. The full key is shown only once, when it is created; CastPDF stores a hash of it and shows only its first 14 characters (the prefix, such as cpdf_live_0123) afterwards. A revoked key stops working immediately. A team can have up to 20 active keys.
Call GET /v1/account to see which team and key mode a key belongs to.
Test keys and live keys
Both kinds of key use the same endpoints, request bodies and responses. Develop with a test key, then swap in a live key.
Test key (cpdf_test_) | Live key (cpdf_live_) | |
|---|---|---|
| Watermark | "CASTPDF TEST" diagonally on every page | None. On the Free plan, a small "Made with CastPDF · castpdf.com" footer on every page (details) |
| Counts towards your plan | No, never | Yes: one successful document is one document, whatever its page count |
| Plan limit errors | Never (plan_limit_reached and spending_cap_reached only apply to live keys) | When the included documents are used up and overage is not available, or the spending cap is reached |
| Rate limit | 20 requests per minute, on every plan | Your plan's limit (see below) |
| PDF storage | 1 day, and only when you ask for a url response or send an Idempotency-Key | Your plan's file retention |
| Documents it can read | Test documents only | Every document of the team |
| Templates | Read and preview only (changes get 403 forbidden) | Create, update, pin and delete |
| Creating the key | Any time | Needs a verified email address |
Page count, rendering, fonts and every other behaviour are identical; only the watermark (or, on the Free plan, the live footer) and the accounting differ.
Previews (POST /v1/templates/:id/preview) are always watermarked and never counted, even with a live key.
A PDF made with the dashboard editor's Generate PDF button is a live document: it has no watermark (on the Free plan it carries the same small footer as live-key PDFs), is stored for your plan's file retention and counts towards your plan like a live-key document.
Rate limits
Limits apply per team and per key mode, per minute: all live keys of a team share one budget, and all test keys share another. The dashboard's previews and test renders draw from the test budget; its Generate PDF button draws from the team's live budget, shared with your live keys.
| Key | Requests per minute |
|---|---|
| Live key, Free plan | 30 |
| Live key, Starter plan | 60 |
| Live key, Growth plan | 120 |
| Live key, Pro plan | 300 |
| Live key, Scale plan | 600 |
| Test key (any plan) | 20 |
Previews have an extra limit of 30 per minute per team and key mode; the dashboard editor's live preview shares the test-mode preview limit. Responses to authenticated requests report the budget in x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (seconds until the window resets); a 429 also carries Retry-After. The details are on the errors and rate limits page.
Suspended teams
If a team is suspended, its keys get 403 with the code forbidden and a message asking you to contact support.