---
title: "Password-protect a PDF"
method: POST
path: "/pdf/protect"
tags: ["PDF tools"]
---

# Password-protect a PDF

`POST /pdf/protect`

## Request

- Base URL: `https://api.podpdf.com`
- URL: `https://api.podpdf.com/pdf/protect`
- Auth: API key in header `X-API-Key`

Returns a copy of one PDF encrypted with AES-256. Set `user_password` (needed to open
the PDF), `owner_password` with `permissions` (restrict printing, copying or editing), or
both.

Send the PDF in the request (up to 4 MB), or upload it with `/pdf/upload-url` and pass
its key as `source_key` (up to 150 MB and 5000 pages). Either way it is one request:
there is no background job. Passwords are used to write the file and are never stored,
logged or returned.

A PDF that is already protected is refused with `422 PDF_ENCRYPTED`.

## Request body

- ProtectRequest: The PDF — `input` inline (up to 4 MB) or `source_key` from `/pdf/upload-url` (up to 150 MB) — and at least one of `user_password` and `owner_password`.
  - `input` InlinePdf: A PDF sent with the request instead of uploaded first. Up to 4 MB.
    - `pdf_base64` string, byte, required
    - `filename` string
  - `source_key` string: Key from `/pdf/upload-url`. Give this or `input`.
  - `filename` string: The name of an uploaded PDF, used for the output name.
  - `user_password` string, password: Needed to open the PDF. Up to 127 bytes, no control characters.
  - `owner_password` string, password: Needed to change or remove the protection. Required when `permissions` restricts anything, and must differ from `user_password`. On its own it needs at least one restriction.
  - `permissions` ProtectPermissions: What a reader may do with the protected PDF. Everything is allowed unless restricted here; restricting anything needs `owner_password`. Screen readers can always read the text.
    - `print` 'full' | 'low' | 'none': `low` allows low-resolution printing only.
    - `copy` boolean: Copying text and images.
    - `modify` boolean: Editing the document.
    - `annotate` boolean: Comments and annotations.
    - `fill_forms` boolean: Filling in form fields.
    - `assemble` boolean: Inserting, deleting and rotating pages.
  - `options` object
    - `output_filename` string: Without `.pdf`. Defaults to the input name with `-protected`.
  - `store` boolean: Store the result and return a download link instead of the file.

## Response `200`

The protected PDF, or JSON when `store` is true or the PDF was given by `source_key`

- PdfSecurityResult: A stored protect or unlock result. The one output's link is also given as `download_url`.
  - `job_id` string
  - `operation` 'pdf_protect' | 'pdf_unlock'
  - `status` 'completed'
  - `input_pages` integer
  - `output_count` 1
  - `download_url` string, uri: Signed link, valid one hour.
  - `outputs` PdfOutputFile[]
    - `index` integer
    - `name` string
    - `pages` integer
    - `page_range` string: The pages of the input this file holds.
    - `size_bytes` integer
    - `warnings` string[]
    - `download_url` string, uri: Signed link, valid one hour.
  - `zip_url` string, nullable: Always null, as there is one output.
  - `download_url_expires_at` string, date-time
  - `warnings` string[]: `SIGNATURE_INVALIDATED`, `SOURCE_REPAIRED` or `NON_ASCII_PASSWORD`.

## Other responses

- `400`: The request was invalid
- `401`: Missing or invalid API key
- `403`: `INSUFFICIENT_CREDITS`, `CONVERSION_TYPE_NOT_ENABLED`, `PDF_TOOLS_NOT_ENABLED`, `RATE_LIMIT_EXCEEDED` or `ACCOUNT_NOT_FOUND`. Note that a plan's rate limit is a 403, not a 429.
- `404`: No such resource for this account
- `408`: `PDFOP_TIMEOUT` — the request took longer than 25 seconds. Nothing is charged.
- `413`: The request body is over the limit
- `422`: The request is well formed but this PDF or password cannot satisfy it: `INVALID_PDF`, `PDF_NO_PAGES`, `PDF_ENCRYPTED` (already protected; unlock it first), `PDF_PASSWORD_INCORRECT` (also when the owner password is needed: `details.needs`), `PDF_NOT_ENCRYPTED`, `PDF_ENCRYPTION_UNSUPPORTED` or `PDF_SECURITY_FAILED`.

---

[API](https://skmtc.dev/podpdf/apis/podpdf-api.md) · [All operations](https://skmtc.dev/podpdf/apis/podpdf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/podpdf/apis/podpdf-api/revisions/84eb21f3ee27?raw)