Add Password to PDF

Add password and security limitations to PDF

Try it live: Add Password to PDF → API Tester — send a real request from your browser.

POST /v1/pdf/security/add

Modifying Restriction Settings: To modify assembly or extraction settings that control PDF restrictions (such as allowPrintDocument, allowFillForms, allowModifyDocument, allowAssemblyDocument, and related permission settings), you must use the ownerPassword in your request. The userPassword alone cannot modify these permission settings. Attempting to change these restrictions with only a userPassword will result in an error: "This file is password-protected. Please ensure you've entered the correct password…". This requirement applies only when making changes to those restrictions.

Attributes

Attributes are case-sensitive and should be inside JSON for POST request. for example: { "url": "https://example.com/file1.pdf" }

Attribute	Type	Required	Default	Description
url	string	Yes	-	URL to the source file url attribute
callback	string	No	-	The callback URL (or Webhook) used to receive the POST data. see Webhooks & Callbacks. This is only applicable when async is set to true.
async	boolean	No	false	Set async to true for long processes to run in the background, API will then return a jobId which you can use with the Background Job Check endpoint. Also see Webhooks & Callbacks
name	string	No	-	File name for the generated output, the input must be in string format.
expiration	integer	No	60	Set the expiration time for the output link in minutes. After this specified duration, any generated output file(s) will be automatically deleted from PDF.co Temporary Files Storage. The maximum duration for link expiration varies based on your current subscription plan. To store permanent input files (e.g. re-usable images, pdf templates, documents) consider using PDF.co Built-In Files Storage.
ownerPassword	string	No	-	The main owner password that is used for document encryption and for setting/removing restrictions.
userPassword	string	No	-	The optional user password will be asked for viewing and printing document.
encryptionAlgorithm	string	No	AES_128bit	Encryption algorithm. AES_128bit or higher is recommended. The available algorithms are: RC4_40bit, RC4_128bit, AES_128bit, AES_256bit.
allowAccessibilitySupport	boolean	No	false	Allow or prohibit content extraction for accessibility needs.
allowAssemblyDocument	boolean	No	false	Allow or prohibit assembling the document.
allowPrintDocument	boolean	No	false	Allow or prohibit printing PDF document.
allowFillForms	boolean	No	false	Allow or prohibit the filling of interactive form fields (including signature fields) in the PDF documents.
allowModifyDocument	boolean	No	false	Allow or prohibit modification of PDF document.
allowContentExtraction	boolean	No	false	Allow or prohibit copying content from PDF document.
allowModifyAnnotations	boolean	No	false	Allow or prohibit interacting with text annotations and forms in PDF document.
printQuality	string	No	HighResolution	Allowed printing quality. The available modes are: LowResolution, HighResolution.
profiles	object	No	-	See Profiles for more information.
outputDataFormat	string	No	-	If you require your output as base64 format, set this to base64
DataEncryptionAlgorithm	string	No	-	Controls the encryption algorithm used for data encryption. See User-Controlled Encryption for more information. The available algorithms are: AES128, AES192, AES256.
DataEncryptionKey	string	No	-	Controls the encryption key used for data encryption. See User-Controlled Encryption for more information.
DataEncryptionIV	string	No	-	Controls the encryption IV used for data encryption. See User-Controlled Encryption for more information.
DataDecryptionAlgorithm	string	No	-	Controls the decryption algorithm used for data decryption. See User-Controlled Encryption for more information. The available algorithms are: AES128, AES192, AES256.
DataDecryptionKey	string	No	-	Controls the decryption key used for data decryption. See User-Controlled Encryption for more information.
DataDecryptionIV	string	No	-	Controls the decryption IV used for data decryption. See User-Controlled Encryption for more information.

This restriction applies when userPassword (if any) is entered. This restriction does not apply if the user enters ownerPassword.

Query parameters

No query parameters accepted.

Responses

Parameter	Type	Description
url	string	Direct URL to the final PDF file stored in S3.
outputLinkValidTill	string	Timestamp indicating when the output link will expire
pageCount	integer	Number of pages in the PDF document.
error	boolean	Indicates whether an error occurred (false means success)
status	string	Status code of the request (200, 404, 500, etc.). For more information, see Response Codes.
name	string	Name of the output file
credits	integer	Number of credits consumed by the request
remainingCredits	integer	Number of credits remaining in the account
duration	integer	Time taken for the operation in milliseconds

Example Payload

To see the request size limits, please refer to the Request Size Limits.

{
  "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-merge/sample1.pdf",
  "ownerPassword": "12345",
  "userPassword": "54321",
  "EncryptionAlgorithm": "AES_128bit",
  "AllowPrintDocument": false,
  "AllowFillForms": false,
  "AllowModifyDocument": false,
  "AllowContentExtraction": false,
  "AllowModifyAnnotations": false,
  "PrintQuality": "LowResolution",
  "name": "output-protected.pdf",
  "async": false
}

Example Response

To see the main response codes, please refer to the Response Codes page.

{
  "url": "https://pdf-temp-files.s3.amazonaws.com/eaa441ade38548b8a3a96d8014c4f463/sample1.pdf",
  "pageCount": 1,
  "error": false,
  "status": 200,
  "name": "sample1.pdf",
  "remainingCredits": 616208,
  "credits": 14
}

Inconsistent URL Encoding in cURL Output: When using cURL to make API requests, the output JSON may show URL characters encoded as Unicode escape sequences. For example, the ampersand character (&) may appear as \u0026 in the cURL output. This is normal JSON encoding behavior and does not affect the validity of the URL. The URL will function correctly when used, as JSON parsers automatically decode these escape sequences. If you’re parsing the response programmatically, your JSON parser will handle this conversion automatically.

Code Samples

CURL

curl --location --request POST 'https://api.pdf.co/v1/pdf/security/add' \
--header 'x-api-key: *******************' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-merge/sample1.pdf",
"ownerPassword": "12345",
"userPassword": "54321",
"EncryptionAlgorithm": "AES_128bit",
"AllowPrintDocument": false,
"AllowFillForms": false,
"AllowModifyDocument": false,
"AllowContentExtraction": false,
"AllowModifyAnnotations": false,
"PrintQuality": "LowResolution",
"name": "output-protected.pdf",
"async": false
}'