Basics for Tvarka Sign and Tvarka Proof

Version 1.30.0

Tvarka Sign and Tvarka Proof work the same way. One API key opens both. Paid requests are charged to the same prepaid balance.

Your first request

Create an API key in your workspace. Send it as a bearer token. A key that starts with tsk_test_ works in the sandbox.

BASE=https://sign-api.tvarka.pro
# TVARKA_KEY holds your API key.
curl -sS "$BASE/v1/me" \
  -H "Authorization: Bearer $TVARKA_KEY"

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 a managing employee (Vadovaujantis darbuotojas) who may manage people opens Users and access, enters the email address and chooses Employee or Managing employee with the rights to give. 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.

Paid API calls work only when there is enough money on the company's balance. Add money to the balance in Billing before your first call. Until then, every paid call answers 402 payment-required.

The workspace manager or an active managing employee who may manage people administers company API access. A managing employee who may manage payments can also 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. Flattening allows up to 1,000 pages, 5,000 widgets, 10,000 annotations and 10,000 field-tree nodes, with field depth up to 64. These limits are shared across a batch. A cooperative 20-second processing budget stops work between PDF operations; it cannot interrupt an individual parser or writer call. A refusal returns HTTP 400 with a flatten error pointer. Split the batch or flatten before upload.

Erasure

POST /v1/erasure erases terminal signings and headless signature files in pages. Set limit from 1 to 100 (default 20), and optionally before to an ISO datetime. While hasMore is true, pass nextCursor as the next request's cursor. The cursor keeps the same client and cutoff; omit before on continuation or keep its original value. A page finishes its current resource and returns after ten seconds of processing; an individual storage call still has its own timeout. failedResources identifies failures, which remain retryable. Finish the pages, then retry without a cursor to revisit failures. hasMore: false ends the traversal; it does not mean failures were erased. In-flight signings and pre-existing shared vault documents remain intact.

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.

A temporary webhook-address lookup failure returns 503 callback-resolution-unavailable with Retry-After. Wait, then retry the same request with the same idempotency key. This refusal happens before resource creation. An ambiguous setup failure still requires reconciliation; keep its key and contact support.

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.

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.

Webhook subscriptions

Automation platforms register their own callback URL: POST /v1/webhooks with url and events answers 201 with a Location header, and DELETE on that location turns it off. The subscription receives the chosen events of every signing this integration creates, signed with the same webhook secret. Each delivery carries eventId (the idempotency key), webhookId and the whole signing, without ceremony links. Answer 410 to remove a subscription from the receiving side. GET /v1/me tests a key and names its workspace; the key may also be sent as X-Api-Key.

Retries, redirects and credentials

Recent contract changes

Pricing

Signatures and timestamps are billed to your Tvarka Sign workspace at the prices of the Sign app. There is no separate API tariff. Kiek naudojate, tiek ir mokate. Jokių prenumeratų.

EUR each, excluding VAT
WhatPrice
Qualified signature, Smart-ID / Mobile-ID / LT IDEUR 0.19
Qualified signature, ID card / USB tokenEUR 0.13
Qualified timestamp, or web page captureEUR 0.19
Web page capture from a chosen country, state, city or ZIP, per placeEUR 0.49
Cookie test: the page as opened, then after "reject all"EUR 0.99
Non-qualified timestampEUR 0.13

The qualified timestamp of a signature is included. From 1 000 qualified signatures a month the price is agreed individually, and an agreed tariff takes precedence. Sandbox is free. Full pricing and allowances. A company outside Lithuania reads tvarka.eu pricing.

Next, pick a product

Questions: info@tvarka.pro