All changes

added settings.security accepted on POST /api/v1/pdf/render. Sub-fields: algorithm (aes_128 | aes_256), open_password, owner_password, permissions{print,modify,copy,annotate,fill_forms,extract_accessibility,assemble,print_high_quality}. Passwords capped at 32 UTF-8 bytes.

added /capabilities/ gains a 10th card 'Password + permission locks' with the full 8-permission expandable list. JSON-LD ItemList numberOfItems goes from 9 to 10. /pricing/ Pro and Enterprise feature lists each gain one security row.

added xAdmin PDF Policy gains document.security.allow and document.security.allowed_algorithms toggles per tier; Pro packs ship with aes_128 only, Enterprise packs ship with both algorithms + owner_password + permissions.

security metadata stream is encrypted alongside the rest of the document; /EncryptMetadata writes true.

improved API-002 explicitly lists the most common settings.security misuses (semantic-invalid security object, password >32 UTF-8 bytes, current token policy doesn't permit the algorithm, combined with settings.profile or settings.e_invoice).

What’s new

POST /api/v1/pdf/render now accepts a settings.security object that turns on PDF standard-security-handler encryption on the output PDF. This is the first time gPdf produces an encrypted PDF — previous releases only emitted plain (or PDF/A) documents.

The shape

{
  "settings": {
    "security": {
      "algorithm": "aes_256",
      "open_password": "***",
      "owner_password": "***",
      "permissions": {
        "print": true,
        "modify": false,
        "copy": false,
        "annotate": false,
        "fill_forms": true,
        "extract_accessibility": true,
        "assemble": false,
        "print_high_quality": true
      }
    }
  },
  "pages": []
}

algorithm — aes_128 (default; PDF 1.7 standard-security-handler revision 4, V=4, AESV2 crypt filter) or aes_256 (PDF 2.0 revision 6, V=5, AESV3).
open_password — required to open the PDF. Omitting it (or sending null, empty string, or whitespace-only) means the document isn’t encrypted.
owner_password — separate from open_password (must differ if both supplied). Provides full owner rights; required when permissions restricts anything. Enterprise only.
permissions — 8 booleans, default true. Setting any to false requires owner_password. Enterprise only.

Tier policy

	Pro	Enterprise
Algorithms	AES-128 only	AES-128 or AES-256
`open_password`	✓	✓
`owner_password`	—	✓
`permissions`	—	✓

Mutual exclusions

settings.security cannot combine with:

settings.profile (PDF/A) — encryption is incompatible with the PDF/A archival contract by spec. Mixing them returns API-002.
settings.e_invoice — Factur-X / ZUGFeRD PDFs must remain machine-readable for the embedded XML pipeline. Mixing returns API-002.

Error surface

The new API-002 triggers for invalid settings.security:

unrecognized algorithm value → API-001 with explicit message
password longer than 32 UTF-8 bytes
permissions provided without owner_password
current token’s xAdmin PDF Policy doesn’t allow the requested algorithm
combined with settings.profile or settings.e_invoice

See the error codes section for the full enumeration.

Where this shows up on the site

/capabilities/ — card 10, with an expandable list of all 8 permission bits.
/pricing/ — Pro and Enterprise feature lists each gained one row describing the new security capability.
/docs/api-reference/ — settings.security is documented under the request reference with the full sub-field table.

Compatibility

settings.security is purely additive — requests that don’t include it produce exactly the same output bytes as before. Existing integrations need no changes.