Digital Signatures

Digitally Sign a Layer

Use this endpoint to digitally sign a document's layer.

You can apply a signature to a specific Instant layer. This lets you maintain independent versions of the same document with separate signatures. For example, if you're working on a contract, you can maintain two layers: one for the original document, and one for a copy that will be digitally signed.

You can sign an Instant layer using the parent document ID and the layer name. If you use a layer name that maps to a non-existing layer, it will be copied automatically from the document base layer and then signed.

Signing Service

The actual signing of the current state of the document is performed by a signing service callback that needs to be maintained and operated separately. It needs to expose a single HTTP endpoint that receives all callbacks required during the document signing flow differentiated by an action property in the request's JSON.

URL of the signing service needs to be configured via SIGNING_SERVICE_URL environment variable.

Watermark and Graphic

The appearance of a digital signature can include a watermark, which is an image typically depicting a company logo or stamp placed in the center, and a graphic, which is an image usually containing the signer's name in the form of a handwritten signature image positioned on the left side of the signature. You can find more information about these different signature appearance options at https://www.nutrient.io/guides/document-engine/signatures/signature-lifecycle/configure-digital-signature-appearance/.

To specify the image to be used as the watermark or graphic in the digital signature, send a multipart request with the application/json part containing the sign request options and the image part containing the watermark image, and the graphicImage part containing the graphic.

post/api/documents/{documentId}/layers/{layerName}/sign

Request

  • Base URL: http://localhost:5000
  • URL: http://localhost:5000/api/documents/{documentId}/layers/{layerName}/sign
  • Auth: one of:
    • API key in header Authorization
    • HTTP bearer

Path parameters

documentIdstring required

The document ID

layerNamestring required

The layer name

Headers

pspdfkit-pdf-passwordstring

The PDF document password.

The value can be either a plain-text password or a base64 encoded password in a form base64:<encoded-password>. Use the Base64 encoding if your password contains characters that are not allowed in HTTP header or would be otherwise mangled (e.g. trailing or leading spaces)

If the document is password protected, any operations performed on it require supplying a password.

Request body

flattenboolean

Controls whether to flatten the document before signing it. This is useful when you want the document's appearance to remain stable before signing and to ensure there's no indication that the document can be edited after signing.

Note that the resulting document's records (annotations and form fields) will be deleted.

formFieldNamestring

Name of the signature form field to sign. Use this when signing an existing signature form field. If a signature field with this name does not exist in the document, it will be created at the position specified with position.

If a signature field with the specified name exists and position is also set, the request will result in an error.

Note: Either formFieldName or position must be provided if creating a visible signature.

signatureType'cms' | 'cades' required

The signature type to create.

cadesLevel'b-lt' | 'b-t' | 'b-b'

The CAdES level to use when creating the signature. The default value is CAdES B-LT. This parameter is ignored when the signatureType is cms.

This is more like a hint of what level to use, and you should be aware that the API can return b-b even when you ask for b-lt. This can happen when the timestamp authority server is down, etc.

You can override the default with the following environment variable: DIGITAL_SIGNATURE_CADES_LEVEL.

For Long-Term Validation (LTV) of the signature, you need to ensure that the signing certificate chain links to a trusted anchor Certificate Authority (CA) at the time of signing.

To add the root CA and necessary intermediate CAs to your Document Engine instance, follow the instructions in our guide on Providing Trusted Root Certificates.

signatureContainer'pkcs7' | 'raw'

Controls the signature container that will be requested from the signing service:

  • pkcs7 - signing service is expected to return PKCS#7 container with signed data.
  • raw - signing service is expected to return RSA signed data directly. Expects PKCS#1 v1.5 signed data.

The default value is pkcs7.

hashAlgorithm'md5' | 'sha160' | 'sha224' | 'sha256' | 'sha384' | 'sha512'

The hash algorithm to use when computing the digest of the document.

The default value is sha256. It is recommended to use sha256 or better.

certificatesstring[]

A set of base64-encoded X.509 certificates that will be used to sign the document.

Required for raw signature container or cades signature type. If not provided, will be requested from the signing service.

signingTokenstring

A string token that will be forwarded to the underlying signing service.

estimatedSizeinteger

Estimated size of the signature (in bytes). The estimated size is the size for the signature that will be reserved in the PDF document before digitally signing it.

A big estimated size will possibly make the signed document bigger than necessary, but a too small one will cause the signing process to fail. The value will be clamped to the nearest even value between 0 and 256 KB (262144 bytes).

By default, Document Engine will set a size of 32 KB (32768 bytes), which should be enough to support even complex certificates.

ℹ️ Note: The estimatedSize corresponds to the /Contents field of the signature field — that is, the signature container. The size of the signature container mostly depends on the complexity of the certificates used for digital signatures.

Example request

{
  "signatureContainer": "raw",
  "signatureType": "cades",
  "signingToken": "user-1-with-rights",
  "flatten": false,
  "appearance": {
    "mode": "signatureOnly",
    "contentType": "image/png",
    "showSigner": true,
    "showReason": true,
    "showLocation": true,
    "showWatermark": true,
    "showSignDate": true
  },
  "position": {
    "pageIndex": 0,
    "rect": [
      0,
      0,
      100,
      100
    ]
  },
  "signatureMetadata": {
    "signerName": "John Appleseed",
    "signatureReason": "accepted",
    "signatureLocation": "Vienna"
  },
  "cadesLevel": "b-lt"
}

Response

The newly created document layer's digital signature.

Example response

{
  "data": {
    "signerName": "John Appleseed",
    "creationDate": "2013-12-19 14:45:26",
    "signatureReason": "accepted",
    "signatureLocation": "Vienna",
    "validFrom": "2023-12-01T15:34:15Z",
    "validUntil": "2025-11-30T15:34:14Z",
    "signatureFormFQN": "Signature-a9c0376e-15cd-416f-9b8f-bbf341fae0ca",
    "signingCertificateChain": [
      {
        "issuerCommonName": "Example CA",
        "serialNumberHex": "1234567890ABCDEF",
        "subjectCommonName": "John Appleseed",
        "validFrom": "2023-12-01T15:34:15Z",
        "validUntil": "2025-11-30T15:34:14Z"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.