Getting it to the reader / options.password
Password protect a generated PDF
Encrypts the output so a reader is asked for a password before the document opens.
What it is for
For documents that are emailed and contain something the recipient would rather not have sitting in an unlocked attachment: a payslip, a statement, a medical or legal document. The password is applied to the rendered file, so nothing about the markup changes.
The request
Sent to options.password. Everything else on this page is what happens around it.
{
"html": "<!doctype html>...",
"options": {
"password": "a-value-the-recipient-already-knows"
}
}The actual limits
Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.
- The encryption is 40-bit RC4 as defined in the PDF 1.4 specification. It is what every PDF reader in existence can open, and it is not strong cryptography.
- A blank or whitespace-only password is treated as no password.
- It applies to a single render. Merging an encrypted document is not the same operation as encrypting a merged one.
What failure looks like
There is no failure at render time. The failure is a misunderstanding: this stops a document being opened casually by someone it was not sent to, and it will not withstand an attacker with a password cracker and an afternoon. If the threat model is an adversary rather than an accident, this is not the control you want.
Plan availability
Not available on the free plan. Passing a password there returns 403 with plan_required, and it is checked before the document is metered so a rejected call costs nothing.
When this is the wrong tool
When the document is sensitive enough that the encryption strength matters. Use a delivery channel that authenticates the reader instead: a link behind a login, or a portal. A password on a PDF that is emailed alongside the password in the same thread is theatre, and it is worth saying so before building it.
Frequently asked
Is password protection available on the free plan?
Not available on the free plan. Passing a password there returns 403 with plan_required, and it is checked before the document is metered so a rejected call costs nothing.
Where do these numbers come from?
The running implementation. Every figure on this page, from payload ceilings to per-plan limits, is what the API enforces today rather than what a specification says it should. If one of them is wrong, the API is the thing to believe.
Related capabilities
Options that come up in the same request, and one from each of the other groups.
Get a webhook when a PDF render finishes
An address notified after a render, so the calling code does not have to hold the request open waiting.
Render an HTML string to PDF over an API
Send a complete HTML document in the request body and get the PDF bytes back in the response.
Set the PDF page size in an API request
Six named paper sizes, passed in the request options, with A4 as the default when nothing is given.
Print background colours and images in a PDF
Controls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.
Render many PDFs in one API call
Up to several hundred documents in one request, each stored and returned as a link, with per-item success or failure rather than one all-or-nothing result.
Check API usage and remaining document quota
How many documents have been used this billing period, what the limit is, and what the plans are, all readable from the API rather than from a dashboard.
Everything the API does
The full list, grouped by which part of the request it belongs to.
API reference
The complete parameter documentation, including the parts with nothing interesting to say about them.
100 free documents a month, and a playground that runs a real render without a key.