Tvarka Sign API

Version 1.9.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. The signer follows the confirmation steps for their method (signing confirmations). Or sign a hash or a PDF from your own application with Smart-ID or Mobile-ID, with no hosted page (headless signatures). A signature is always a person using their own eID.

Choose your integration

The OpenAPI below defines the supported public request fields. For hosted signing, CreateSigningRequest selects qualified signing; the web client's level: esign invitation field belongs to its separate session-authenticated interface.

n8n integration

Install n8n-nodes-tvarka-sign in self-hosted n8n through Settings → Community Nodes. Follow the maintained installation and credential guide and import the example workflow.

The connector uploads files, creates hosted qualified-signing requests, reads or lists them, downloads results, cancels requests and sends reminders. Use a Sign workspace key; DD and ATK keys are separate. It does not start headless signatures or the web application's simple e-signatures. Request creation is not signature completion.

The example needs your credentials and an uploaded file token. It explicitly sends email invitations, waits between status checks and downloads only after completion. Replace its example inputs before running; protect execution data and ceremony links. Existing sandbox keys simulate and return a sandbox-marked download. n8n Cloud installation requires n8n verification; npm publication alone does not establish Cloud availability.

Signing confirmations

Hosted and headless Smart-ID/Mobile-ID signing share the certificate lookup and signing sequence. A known signing certificate needs one signing PIN. Where the configured certificate service supplies the certificate without a PIN, first use also needs one signing PIN; a new Smart-ID account may first need approval in the app. If the flow instead needs a certificate-capture confirmation, that comes before the document-signing confirmation: two PINs in total. Follow the current verification code, rather than assuming a fixed number of prompts.

For headless signing, render the current step and verificationCode. A transition from authentication to signing can emit signature.confirmation_required; replace the displayed code. Hosted pages handle this for you. The Smart-ID QR/app-link journey opens the Smart-ID app for the signer; follow the hosted page and app prompts. Card/USB and NFC signing use the card's signing PIN through the supported local client; any required identity step is presented in that client.

REST quickstart · Webhook verification · Recent changes

Contract

Endpoints

MCP server

Tvarka Sign 1.9.0, Streamable HTTP at /mcp, registry name pro.tvarka/sign. Documents come from the workspace vault, Markdown text, a link, a chat attachment or base64.

Agents: Claude, ChatGPT, Gemini, Copilot

Connect Tvarka Sign to your assistant once; then ask it to send a document for signature, track it and fetch the signed original. Server URL: https://sign-api.tvarka.pro/mcp. The assistant opens a Tvarka page, you confirm with your eID, choose the company and allow the connection. It then acts as you, with your rights in that company, and signatures are billed to the company as usual. No key is pasted anywhere.

What the assistant can do: write the document as text and have Tvarka render it to PDF/A, send a PDF from a link or a chat attachment, add you as the first signer, set a signing order and deadlines, remind, add signers, cancel, and hand you a download link for the signed document. It never signs: every signature is a person with their own eID. Connections are listed, with last use, under Settings, API settings, Connected apps, and end with one click.

Your API key

  1. Copy your production key. Select the company and open Settings. Every active, identified company member with Sign access has API access automatically. Click Show or Copy beside API key. No separate request or administrator approval is needed. The secret is prepared on first use and reused on later visits.
  2. Invite a colleague. A manager (Vadovas) or full-rights representative (Atstovas) opens Users and access, enters the email address and chooses Employee or Representative (all rights). The only API checkbox requests an optional password-protected ZIP email; it does not grant API access. No personal code is needed on the invitation form. The invitation arrives first; requested credentials are prepared after identity confirmation.
  3. Optional ZIP delivery. The AES-256 ZIP contains credentials.json and README.txt, including the API key and webhook secret. Its password is the last four digits of the employee's personal code (asmens kodas), including leading zeroes. Open it with 7-Zip or Keka. Credentials are never included in the email body. The key remains available in Settings.

Show and Copy need no additional eID check. Only the owner can reveal a key. Existing production integrations keep their keys and signing history. For a historical hash-only key, Settings explains that Show/Copy prepares a recoverable companion on that same integration, leaving the original key valid. A deliberately revoked key is never silently recreated. Manage key retains advanced controls and existing sandbox integrations. Sandbox is retired from ordinary onboarding; existing sandbox keys continue working.

Send Authorization: Bearer <key> for REST and MCP. tsk_live_ selects production; tsk_test_ selects sandbox. The key acts as the named employee in the selected company workspace. Keep it in your application's secret store. Sandbox simulation needs no funding.

Company and billing. Each key stays bound to one company workspace; changing the company selected in your browser does not move the key, its documents, charges or prepaid balance. The same user can hold separate keys for several companies. Check the company name and code beside the key in Settings and in the downloaded credentials. Personal signing is a separate context and does not change an API key's company.

The workspace manager or an active full-rights representative administers company API access; a limited managing-employee role does not grant company administration. Full-rights representatives can also invite other representatives and set up billing. Restricted members can open Billing to see the required steps without seeing financial data. A payment-required response identifies the key's company in billingContext; canManageBilling describes the key owner's permission. If false, ask a company administrator to open recoveryUrl after signing in and resolve the payment issue.

Change, resend or revoke

Users and access shows Change rights, Send API key and API settings directly in each user row; there is no More menu. Suspension and removal also have visible actions. API settings contains rotation and revocation for each existing integration.

Removing the employee's company role permanently revokes their API access; restoring the role does not restore old keys. Suspended access blocks API use. User and credential management remain available during a billing soft lock, while normal document operations retain their billing checks. ATK and Due Diligence use their own credentials and onboarding; Sign API keys do not grant access to those APIs.

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.

Since v1.9.0, Office files and images (.docx, .doc, .odt, .rtf, .xlsx, .xls, .ods, .pptx, .odp, .txt, .jpg, .jpeg, .png) are converted to PDF/A-2b before signing, including file uploads and URL intake. The resulting PDF is signed; the original is not retained. POST /v1/conversions returns just the PDF, without storing or signing it. Conversion has no additional charge and uses Tvarka's conversion service. An unreadable file returns 422; unavailable conversion returns 503.

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.

Custom PDF stamps

Custom stamps are activated for clients with a signed agreement. The stamp entitlement covers a company logo and exact PDF placement in both Tvarka Sign and the API. VIP whitelabel is a separate entitlement for changing or removing the vendor line. Standard clients keep the default Tvarka line; the Tekstas po parašu controls are hidden without VIP access. Contact [email protected] for activation.

Configure your workspace

The active company Vadovas opens Users and access → Parašo išvaizda in the cloud browser. Choose the company workspace, upload its logo, preview, then save. The tab remains visible with disabled controls until activation, even when the developer API is disabled. Tvarka operators manage the stamp and VIP entitlements in Administravimas → Parašo išvaizda; a customer cannot activate either entitlement themselves.

These are browser settings, not new bearer-key REST endpoints or MCP tools. Do not add logo, tagline or entitlement fields to signing requests.

Place an API signer's stamp

Add visibleSignature to each signing party. Choose exactly one of these signer objects (replace the sample email):

{
  "email": "[email protected]",
  "visibleSignature": {"page": 1, "x": 36, "y": 36, "width": 148, "height": 52}
}
{
  "email": "[email protected]",
  "visibleSignature": {"field": "Sig_Vadovas"}
}

Shared appearance, separate placements

Each API order freezes its effective logo and vendor line on acceptance, including later signers, retries and idempotent replays. Editing or resetting workspace branding, or revoking stamp/VIP access, does not change that snapshot. New explicit placements, including add-signer, still require stamp entitlement. After VIP revocation, new snapshots use the default Tvarka line.

Regular Sign uses the same workspace branding for remote, USB/NFC and invited signing. Its Mano parašo vieta editor lets a user preview and save their own qualified PDF signature's coordinates or existing field; API-owned placement remains controlled by the API order. Sign freezes branding when signing, pairing, an internal-signature job or an invitation first begins; signed outputs retain the source snapshot. Internal electronic signatures keep their non-qualified label and existing overlay position. Personal signing and non-PDF containers retain their existing behavior.

Preview and handle failures

Sandbox /simulate completion renders the requested placements and snapshotted branding, including default-corner signers, branding-only orders and MCP orders from vault documents. The artifact is conspicuously unsigned. Already-signed input stays byte-identical and receives no stamp preview.

Same-tab signing and automatic return

Send the signer to their ceremonyUrl in the current browser tab. Add returnUrl and a random, session-bound returnState (16-128 URL-safe ASCII characters) when creating the signing or batch. Contact Tvarka to register your exact HTTPS return URL for your API client first.

After signing or declining, the browser returns automatically with state, signingId, signerId and result. Results are signed, declined, cancelled, expired, simulated (sandbox), or returned when the signer chooses Return to your application. Returning early leaves the signing request open. Match state to the browser session and retrieve the signing through your backend or verify its webhook; URL parameters are never proof of a signature. One signer's completion need not complete the order.

The hosted page retains its anti-framing protection. An iframe allows the surrounding page to overlay signing controls; same-tab navigation keeps document review in Tvarka.

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

Upload documents up to 100 MB (100,000,000 bytes) with multipart POST /v1/files: one binary part named file, retaining its filename extension. Use the returned fileToken in document.fileToken. Existing JSON/base64 uploads remain available up to 15 MiB decoded. Signed outputs may grow as signature evidence is added.

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.

REST sandbox quickstart

Use a POSIX shell with curl, jq and Python 3. Set TVARKA_SIGN_KEY in your local environment to an existing tsk_test_ key. Ordinary self-service onboarding creates production access; if you have no sandbox integration, request test access from [email protected]. Sign, Due Diligence and ATK keys are separate.

Use a small synthetic unsigned PDF named example.pdf. This flow uploads it, creates a link-delivered request without sending an invitation email, simulates completion, polls and verifies the downloaded artifact. Run each create step once; retain its JSON body, key and returned ID before retrying.

set -eu
# Use an existing sandbox key. Never put a production key in this example.
case "$TVARKA_SIGN_KEY" in tsk_test_*) ;; *) echo "Use a sandbox key"; exit 1;; esac
BASE=https://sign-api.tvarka.pro
# Save any small, unsigned PDF as example.pdf before running this block.
# Keep this idempotency key and create.json for a retry of THIS signing.
IDEMPOTENCY_KEY="quickstart-$(python3 -c 'import uuid; print(uuid.uuid4())')"
TOKEN=$(curl --fail-with-body -sS "$BASE/v1/files" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" \
  -F 'file=@example.pdf;type=application/pdf' | jq -er '.fileToken')
jq -n --arg token "$TOKEN" '{title:"Sandbox example",document:{fileToken:$token},delivery:"link",signers:[{email:"reader@example.test",name:"Example Reader",language:"en"}]}' > create.json
curl --fail-with-body -sS "$BASE/v1/signings" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" --data-binary @create.json > signing.json
SIGNING=$(jq -er '.signingId' signing.json)
curl --fail-with-body -sS "$BASE/v1/signings/$SIGNING/simulate" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -H 'Content-Type: application/json' \
  -d '{"action":"complete"}' > simulated.json
curl --fail-with-body -sS "$BASE/v1/signings/$SIGNING" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" > result.json
jq -e '.status == "completed" and .completionMode == "sandbox_simulation" and .document.sandbox == true and .document.signed == false' result.json
curl --fail-with-body -sS "$BASE/v1/signings/$SIGNING/document" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -D artifact.headers -o sandbox-result.pdf
python3 - <<'PY'
import hashlib, json
from pathlib import Path
result = json.loads(Path('result.json').read_text())
assert 'x-tvarka-sandbox: simulated-artifact-no-signature' in Path('artifact.headers').read_text().lower()
assert hashlib.sha256(Path('sandbox-result.pdf').read_bytes()).hexdigest() == result['document']['sha256']
print('Downloaded sandbox artifact; hash matches. No signature was created.')
PY

Multipart upload accepts up to 100,000,000 bytes; inline/base64 requests accept up to 15 MiB of decoded document bytes. Reuse fileToken for large files. Sandbox completion exercises the lifecycle and download path; it creates no qualified signature. Production uses the real signer ceremony instead of /simulate.

Headless sandbox example

Using the same sandbox environment, this example supplies a synthetic identity and digest. In production, hash the exact document and display the corresponding content to the signer; renderHash records what you showed. Production headless signing needs an enabled workspace and the headless addendum.

# Sandbox only; set HEADLESS_REQUEST_KEY once and retain it for retries.
HEADLESS_REQUEST_KEY="headless-$(python3 -c 'import uuid; print(uuid.uuid4())')"
DIGEST=$(python3 -c 'import hashlib,base64; print(base64.b64encode(hashlib.sha256(b"Synthetic document").digest()).decode())')
jq -n --arg hash "$DIGEST" '{method:"smart_id",signer:{personalCode:"39001010011"},document:{name:"Synthetic document",profile:"cades-detached",hash:{algorithm:"sha256",value:$hash}},display:{text:"Sandbox signing"},renderHash:{algorithm:"sha256",value:$hash}}' > headless.json
curl --fail-with-body -sS "$BASE/v1/signatures" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $HEADLESS_REQUEST_KEY" --data-binary @headless.json > signature.json
SIGNATURE=$(jq -er '.id' signature.json)
curl --fail-with-body -sS "$BASE/v1/signatures/$SIGNATURE/simulate" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY" -H 'Content-Type: application/json' \
  -d '{"action":"sign"}'
curl --fail-with-body -sS "$BASE/v1/signatures/$SIGNATURE" \
  -H "Authorization: Bearer $TVARKA_SIGN_KEY"

Verify webhooks before trusting them

Set a public HTTPS webhookUrl when creating a signing. Verify X-Tvarka-Signature-V2 against the raw body with your integration's webhook secret. V2 authenticates the attempt timestamp as well as the body. The older X-Tvarka-Signature is a body-only HMAC retained for existing consumers.

import hashlib
import hmac
import time


def verify_tvarka_webhook(raw_body: bytes, signature_v2: str, secret: str) -> bool:
    # Call before parsing JSON. Pass the exact request bytes and the integration's
    # webhook secret, not its API key. Keep the server clock synchronized.
    try:
        fields = dict(part.split('=', 1) for part in signature_v2.split(','))
        timestamp = fields['t']
        if abs(time.time() - int(timestamp)) > 300:
            return False
        expected = hmac.new(secret.encode('utf-8'),
                            timestamp.encode('ascii') + b'.' + raw_body,
                            hashlib.sha256).hexdigest()
        return hmac.compare_digest(expected, fields['v1'])
    except (ValueError, KeyError, UnicodeError):
        return False

After verification, parse the JSON and check the signing ID against your own records. Process each event once: use an atomic durable record keyed by the authenticated payload's signing/signature ID, event type and optional signer ID; the supplied X-Tvarka-Idempotency-Key is also stable across retries. Acknowledge with 2xx after durable acceptance, then process asynchronously. Redeliveries may arrive, and polling remains available.

Retries, redirects and credentials

Recent contract changes

Headless signatures

POST /v1/signatures signs one document for one signer with Smart-ID or Mobile-ID, with no hosted page, no invitation and no email. Your application shows the verification code and the signer confirms on their phone. The confirmation sequence depends on the known certificate and configured certificate service. When an identity step comes first, the document-signing step follows with a new code: step moves from authentication to signing and a signature.confirmation_required webhook carries the new code.

Name a profile: cades-detached signs your SHA-256 hash and returns a detached .p7s at CAdES-BASELINE-LT, with the certificate chains and revocation data embedded; pades signs a PDF, such as the PDF/A-2 that ESPBI renders, and returns it signed at PAdES-BASELINE-LT, as an invisible signature added in an incremental update. Send renderHash, the digest of what you showed the signer; it is kept as evidence with the display text, the input digest, the codes and the signing certificate. Production workspaces are enabled by Tvarka after the headless addendum is signed. One signature is billed on success; declined, expired, failed and cancelled ones are free. For many documents at once, sign in bulk with the ID card through the ATK API.

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.

Signature validation

Validate electronic signatures and retrieve advisory validation results for integration into your document workflows.

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ų.

Qualified signatures: EUR per signature, excluding VAT
Monthly QES countSmart-ID / Mobile-ID / LT IDID card / USB token
1-99EUR 0.19EUR 0.13
100-499EUR 0.18EUR 0.10
500-999EUR 0.17EUR 0.08
1000+EUR 0.16EUR 0.06

The qualified timestamp is included. The company's monthly QES count determines the tier; an individually agreed tariff takes precedence. Sandbox is free. Full pricing and allowances.

Questions: [email protected]