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.
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"
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.
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.
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.
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.
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.
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.
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.
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.
Idempotency-Key. After an uncertain response or pending 409, reconcile the original operation before creating another. Do not solve a timeout by minting a new key.Retry-After. Stop automatic retries for invalid input, authentication and billing refusals until corrected. Reconcile a timed-out mutation before repeating it.Retry-After. A failed webhook does not cancel the signing; poll its state.qualified and esign orders: CC copy recipients (role: cc, automatic signed-file copy email on completion, attached up to 10 MiB or a 30-day download link above that), pre-sign approvers (role: approver, guest review and approve/decline page with parked signing invitations until all approvers approve, zero billing on decline, signing.approver_approved and signing.approver_declined webhooks, processingStage: awaiting_approvers), and recipient groups ("any 1 of N" via group on role: signer, retracting remaining peers once one member signs and allowing shared visibleSignature.field within a group).visibleSignature ({"anchor": "...", "offsetX", "offsetY", "width", "height", "occurrence"}) for both qualified and esign signings and headless pades; visibleSignature and returnUrl opened to level: esign; embedded iframe signing via registered embedOrigin with origin-locked postMessage events; and self-serve webhook delivery logs & retry via GET /v1/webhooks/deliveries, POST /v1/webhooks/deliveries/{deliveryId}/retry and the Sign API logs screen. An embedded signing cannot ask for an access code or an SMS code (400). A retry of a delivery that is being sent right now, or of a removed subscription, answers 409..edoc and .scs beside ASiC-E, BDOC and ADOC, ASiC-S, PDFs signed or certified elsewhere, and .p7m for every signer. A file that can never take a signature (an earlier signature broken, a password, a certification that forbids changes, a damaged file) is answered once with 422 document-not-signable and a stable code; do not retry it. A busy converter or validator is still 503 and may be retried.signer.personalCode on POST /v1/signatures is read by country, so an Estonian code locks a Smart-ID signature by QR code or app link. A pinned Estonian signer who signs with Mobile-ID types the phone number only. Return addresses can be registered in the API settings of the Tvarka Sign app.signers[].personalCode and templateRoles[].personalCode is read as a code of your company's country. Write PNOEE- or PNOLT- before the digits to name the country./v1/capture-monitors), bundles of up to 20 addresses (/v1/capture-bundles) and page.quality on every capture.page.locations (2 to 5 places), page.device, page.locale, the cookie test page.consent, page.recheckAt, webhookUrl, secondTimestamp and a WACZ archive of each capture.page.location, a web page captured from a chosen country, state, city or postal code, with the exit recorded in page.exit."qualified": false on POST /v1/timestamps for a simple timestamp of a document or a hash.POST /v1/timestamps, qualified timestamps of a document, a hash or a captured web page, with a public check page.document.file for the headless profiles xades-enveloped, cades-enveloping-xml, asice, edoc and jades.cades-enveloping, the PDF inside the signature as a .pdf.p7m.authority on a signing, one check of each signer against the company's register entry.GET /v1/form-requests, the status staff_pending and signers on a form request.product: forms on POST /v1/kiosk-sessions and channel: kiosk on POST /v1/form-requests./v1/form-templates, /v1/form-requests and the form_request.* webhooks.GET /v1/kiosks and /v1/kiosk-sessions for a drawn signature at the desk.TemplateVisibleSignature, a template's saved box checked by the sizes the Tvarka Sign app saves it with./v1/templates), templateId on POST /v1/signings and sending to a list (/v1/templates/{templateId}/bulk-sends, up to 500 rows).stamp-controls-not-enabled is retired.pades signature, with visibleSignature./v1/webhooks) for automation platforms, GET /v1/me, the externalId filter on GET /v1/signings and the X-Api-Key header.level: esign) with per-signer authentication, processingStage and GET /v1/signings/{signingId}/evidence; headless nextAction, Smart-ID QR code and app link (interaction) and the initiation_unknown outcome.POST /v1/conversions and conversion during document intake.pades profile.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ų.
| What | Price |
|---|---|
| Qualified signature, Smart-ID / Mobile-ID / LT ID | EUR 0.19 |
| Qualified signature, ID card / USB token | EUR 0.13 |
| Qualified timestamp, or web page capture | EUR 0.19 |
| Web page capture from a chosen country, state, city or ZIP, per place | EUR 0.49 |
| Cookie test: the page as opened, then after "reject all" | EUR 0.99 |
| Non-qualified timestamp | EUR 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.
Questions: info@tvarka.pro