Tvarka Sign API

Version 1.2.1

Machine channel for Tvarka Sign: post a document and a list of signers, and Tvarka runs its ordinary qualified signing ceremony for each of them. Each signer confirms with a single PIN entry. No endpoint here signs anything - a signature is always a person using their own eID.

Contract

Endpoints

GET /v1/signings - List signings
POST /v1/signings - Create a signing
GET /v1/signings/{signingId} - Get a signing
PATCH /v1/signings/{signingId} - Update a live signing deadline
DELETE /v1/signings/{signingId} - Erase one signing
POST /v1/batches - Raise one signing per document for one set of parties
GET /v1/batches/{batchId} - Poll a batch and every signing in it
POST /v1/signings/{signingId}/archive - Raise the signed output to a long-term level
POST /v1/files - Store a document once for reuse across signings
GET /v1/files/{fileToken} - Inspect a stored file
DELETE /v1/files/{fileToken} - Purge a stored file
GET /v1/signings/{signingId}/comments - Read the notes on a signing
POST /v1/signings/{signingId}/comments - Add a note to a signing
POST /v1/erasure - Erase terminal signings in bulk
POST /v1/signings/{signingId}/cancel - Cancel a signing
GET /v1/signings/{signingId}/document - Download the signed document
POST /v1/signings/{signingId}/signers - Add a signer to a live signing
PATCH /v1/signings/{signingId}/signers/{signerId} - Update a pending signer's allowed methods
DELETE /v1/signings/{signingId}/signers/{signerId} - Remove a pending signer
POST /v1/signings/{signingId}/signers/{signerId}/remind - Remind one signer
POST /v1/signings/{signingId}/simulate - Drive a sandbox signing to an outcome

MCP server

Tvarka Sign 1.2.1, Streamable HTTP at /mcp, registry name pro.tvarka/sign. Tools address documents already in your workspace vault, so no document has to travel through an agent's context.

list_documents - Documents in the tenant workspace vault that can be sent for signing. Returns documentId values for request_signatures.
request_signatures - Open a qualified signing ceremony on a vault document for one or more signers. Returns a ceremony URL per signer, or emails them directly when delivery is "email". Billed per signature on completion.
get_signing - The current state of one signing and each of its signers.
list_signings - Signings raised by this tenant, newest first.
remind_signer - Re-send one signer their invitation email. Limited to one reminder per signer per hour.
cancel_signing - Retract every outstanding invitation and close the signing. Signatures already collected are untouched and remain valid.

Keys

Provisioned by Tvarka during onboarding and shown once. tsk_live_ is production, tsk_test_ is the sandbox. Send them as Authorization: Bearer <key>. To request access, write to [email protected]: a sandbox tenant costs nothing and its key works before any funding.

Documents you can post

PDF; appendable ASiC-E containers (.asice, .sce, .bdoc); and the ADOC family (.adoc, .bedoc, .cedoc, .gedoc, .ggedoc) to countersign one that is already signed. A container is signed in place, never converted. MDOC is not accepted for countersigning: its composer writes a first signature only.

Instead of one finished file you can send container and have several files composed into a new package that is signed once: asice takes PDFs, adoc takes .pdf and .xlsx, first file is the main document, up to 20 files. document and container are mutually exclusive.

A PDF may set flatten: true to freeze its form fields into page content before signing. It fails closed: if any field has no appearance Tvarka can draw faithfully, nothing is flattened and the response names those fields, because a signed document that does not show what the signer approved is worse than a refused request.

Workflow

Signers are parallel by default. signingOrder: sequential releases them one at a time in the order you posted them, and the signers who are waiting hold a link that answers 404 until their turn, so the order is enforced and not merely unsent. A decline stops the workflow at the decliner's turn: the signing settles declined and the signers still waiting are cancelled. A signer added to a sequential signing joins the end of the queue. A signer may carry role: viewer: a recorded party who is never invited, never blocks completion and is sent nothing - you hold the webhook and the download.

Two deadlines. expiresInDays is the hard one, the date the signing dies. softDeadlineInDays is the date it is wanted by: nothing expires, but every signer who can still sign is reminded once on the day it passes.

Batches and reusable files

POST /v1/files stores a document once and returns a fileToken a later signing may reference instead of carrying base64 again. The bytes are copied into each signing, so deleting a file never reaches into one that already used it.

POST /v1/batches raises one signing per document for one set of parties. It is a grouping, not a single signing act: every document keeps its own ceremony and its own signature, because the ID card produces one signature per document. It buys one call and one identifier to poll, not one PIN for many documents.

POST /v1/signings/{signingId}/comments keeps your own notes on a signing. Comments are not shown to signers.

Long-term signatures

POST /v1/signings/{signingId}/archive raises signed output to a long-term level: PDF to PAdES-B-LT, ASiC-E to XAdES-LT, embedding the chain and revocation evidence so the signature still validates once the certificate has expired. ASiC-E signing already reaches XAdES-LT on its own, so this is for output that arrived at T. ADOC is refused by name: ADOC-V1.0 specifies XAdES-T and its validators expect it.

Errors

RFC 9457 problem documents, and request-body validation collects rather than failing fast: a body with three bad fields comes back once, as validation-failed, with an errors array of {"pointer": "/signers/0/email", "detail": "..."}. The pointer is an RFC 6901 JSON Pointer into what you sent, so a fault maps back to an input without parsing prose.

Sandbox

A tsk_test_ key drives the whole lifecycle, including POST /v1/signings/{signingId}/simulate. A simulated completion returns a real downloadable file, so your download, hashing and storage code runs for real without a card in anyone's hand. The sandbox never adds a signature: an unsigned PDF comes back as your own pages with a banner saying it is not signed, and anything posted already signed comes back byte-identical, because those signatures are somebody else's and are not ours to disturb. Every artifact is flagged sandbox in the response, the webhook and an X-Tvarka-Sandbox header. Tvarka issues no test signatures.

Methods and formats

This orchestration API offers LT ATK card signing over NFC in the Tvarka Sign mobile app, plus Smart-ID and Mobile-ID. The separate ATK API is the full low-level LT ATK surface for NFC, USB/readers and raw signatures. Across Tvarka APIs, PAdES, XAdES, CAdES, JAdES and ASiC cover all Regulation (EU) 2026/248 Annex I families.

Product boundaries

Tvarka offers simple, advisory signature validation. It does not sell qualified validation and it does not offer an electronic-seal API.

Pricing

Signatures are billed to your Tvarka Sign workspace on the ordinary per-signature price ladder. There is no separate API tariff. Kiek naudojate, tiek ir mokate. Jokių prenumeratų.

Questions: [email protected]