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 the worker for a signature, and the worker asks the provider.

Why a worker sits in the middle

Every provider has its own API and its own signer experience:

• One keeps a long-term certificate for each signer and speaks the CSC API, the Cloud Signature Consortium’s standard for remote signing.
• Another identifies the signer on a hosted page, issues a certificate for that one signature and returns a finished signature.
• A third sends a push notification, and the signer approves in its app.

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 any 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 knows who the signer is, records their approval and signs with their key.

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

Three calls

For each qualified signature, SignatureAPI calls the worker three times, in order:

Call	Question	Can wait for the signer?
credential	Which certificate signs, and in which format?	Yes
authorize	Does the signer approve this exact digest?	Yes
sign	What’s the signature?	No

A call that needs the signer answers pending: send the signer’s browser to a page, or let SignatureAPI poll until they approve in an app. Which calls wait, and for what, depends on your provider. Choose your provider’s model works it out.

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 plays a provider that waits for the signer twice: an Identify yourself page during credential, then an Authorize your signature page during authorize. It shows both on purpose, so you see both ceremony screens. Your own worker waits only where your provider needs the signer. Then it 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 one: choose a model, follow a recipe, then build and test

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.

Build a worker

Choose a model

Certificate lifecycle, identification and output: which format, which pauses.

Recipes

CSC remote certificate, one-shot certificate, app approval.

Build and test

The endpoints, the test plan and the go-live checklist.

Protocol reference

Every request, response, error and check.