Signing workers

A qualified signature is made with a certificate and a signing key that a qualified trust service provider (QTSP) holds for the signer. A QTSP is a company that a national supervisory body has approved to issue qualified certificates under eIDAS, the EU regulation on electronic signatures. SignatureAPI is not a QTSP. You choose the provider, and you keep your contract with it.

A signing worker is the small HTTPS service that connects SignatureAPI to that provider. When a qualified signer finishes the ceremony, SignatureAPI asks your worker for a signature, and your worker asks your provider.

Why a worker sits in the middle

Every provider has its own API. One identifies the signer on a hosted web page. Another sends a push notification to the signer’s phone. A third issues a certificate on the spot that is valid for a few minutes.

The worker hides those differences. SignatureAPI speaks one protocol, the Signing Worker Protocol (SWP/1), and the worker translates it into your provider’s API. That’s how you bring your own provider without SignatureAPI building an integration for it.

How the pieces fit

flowchart LR
    Signer["Signer's browser"] <-->|ceremony| API[SignatureAPI]
    API -->|SWP/1 over HTTPS| Worker[Signing worker]
    Worker <-->|provider API| TSP[Qualified trust service provider]
    Signer -.->|identify and approve| TSP

• SignatureAPI runs the envelope and the ceremony. It computes the digest of the document, checks the returned signature and embeds it in the PDF.
• The signing worker gets that digest signed with the signer’s certificate, through the provider.
• The provider identifies the signer, records their approval and signs with their key.

The worker never sees the documents. It receives digests only, and SignatureAPI rejects any signature that doesn’t verify over the digest it sent.

Test mode: the sandbox worker

You don’t need a worker to try qualified signatures. In test mode, when you haven’t connected a worker, the SignatureAPI sandbox worker at https://sandbox-signer.signatureapi.com signs your test envelopes.

It behaves like a real interactive provider. It shows an identification page and an approval page, then signs with a short-lived certificate from a sandbox certificate authority. Those certificates are not qualified, so PDF validators show the signer as not trusted.

Live mode: your own worker

Live envelopes with qualified signers need a worker that you connect for live mode. There is no sandbox fallback in live mode: without an active live worker, creating or sending such an envelope fails with qualified-signing-worker-not-connected. See Go live.

You get a worker in one of two ways:

Your situation	What to do
Your provider, or a partner, runs a signing worker for you	Connect a signing worker with the URL they give you
Nobody runs one for your provider yet	Build a signing worker, then connect it

Either way, the worker’s owner must allow your account before it accepts your requests. You give them your connection token from the Dashboard, and they add it to the worker’s configuration. See Connect a signing worker.

Test and live can use the same worker or different ones. A common setup points test at a worker that uses the provider’s test environment, and live at one that uses production.