Headless signing

Executes document signing without any user interaction

Used when you need to sign or seal documents instantly without requiring user interaction. Headless Signing is a strictly backend operation that integrates with the Sphinx credential system to issue either Advanced Electronic Signatures (AES) for natural persons or Qualified Electronic Seals (QSEAL) for legal entities. The signing process runs entirely server-side: it initiates the signing request, polls for the result, and finalizes the operation — making it ideal for automated workflows and backend-driven processes.

---

Key features

• Strictly headless — No UI, no user interaction required; executes purely server-side
• Two signing modes — Supports AES (Advanced Electronic Signature for individuals) and QSEAL (Qualified Electronic Seal for organizations)
• Sphinx credentials — Uses the same credential system as ELECTRONIC_SIGNATURE:v1 for issuing signatures
• Async polling — Initiates the signing request, polls for completion, and finalizes the result in a Temporal workflow
• Automatic signature issuance — Instantly signs documents using available identity or entity data

---

Configuration

Attribute	Type	Required	Description
mode	string	Yes	Signing mode: AES (Advanced Electronic Signature for natural persons) or QSEAL (Qualified Electronic Seal for legal entities).
config	Object	Yes	Environment-specific configuration for the InstantSign provider.
config.live.shortname	String	Yes	The InstantSign provider shortname for the live environment.
config.staging.shortname	String	Yes	The InstantSign provider shortname for the staging environment.

---

Signing modes

AES (Advanced Electronic Signature)

Used for signing documents on behalf of natural persons. Requires verified identity information.

Input requirements:

• DocumentsToSign — The documents to be signed
• BasicIdentity — The signer's identity data (given name, family name)

Credential binding: The signature is linked to the individual's verified identity from the BasicIdentity datablock.

QSEAL (Qualified Electronic Seal)

Used for sealing documents on behalf of legal entities. Does not require individual identity information — the seal is bound to the entity's credential.

Input requirements:

• DocumentsToSign — The documents to be sealed

Credential binding: The seal is bound to the organization's entity credential, not an individual.

---

Input data blocks

Data block	Required	Mode	Description
DocumentsToSign	Yes	Both	The documents to be signed or sealed. References uploaded documents via vault URIs.
BasicIdentity	Conditional	AES	The signer's identity information (given name, family name). Required only for AES mode.

File size limit

Each file referenced in DocumentsToSign must not exceed 20 MB. Exceeding this limit returns HTTP 422 with error code FILE_TOO_LARGE at session creation.

---

Verdicts

Verdict	Description
success	The document was signed or sealed successfully. The signing process completed without errors and the signature is valid and legally binding according to eIDAS rules.

---

Output data blocks

Verdict	Data blocks produced	Description
success	SignedDocumentsPackage	Contains the signature process ID and vault references to the signed/sealed documents.

SignedDocumentsPackage — success

Field	Type	Description
signatureProcessId	string	Identifier of the signature process (transaction number) for audit and tracking.
signedDocuments.mode	string	Delivery mode: archive, items, or both.
signedDocuments.archive	object	Vault reference to the ZIP archive containing signed documents (when applicable).
signedDocuments.documents	array	Individual signed document references with their vault URIs.
signedDocuments.documents[].templateId	string	Identifier for the template used for the electronic signature.
signedDocuments.documents[].signed	object	Vault reference to the signed PDF file.
createdAt	string	ISO 8601 timestamp of when the signed documents package was created.

---

Example configuration

AES — Sign documents with individual identity

{
  "mode": "AES",
  "config": {
    "live": {
      "shortname": "my-sphinx-live"
    },
    "staging": {
      "shortname": "my-sphinx-staging"
    }
  }
}

QSEAL — Seal documents with entity credential

{
  "mode": "QSEAL",
  "config": {
    "live": {
      "shortname": "my-sphinx-live"
    },
    "staging": {
      "shortname": "my-sphinx-staging"
    }
  }
}