# Tvarka ATK API

Lithuanian eID (ATK) card authentication and qualified electronic signing
over HTTP. A relying party creates a request server-to-server; the card signs
an audience-bound challenge on the user's own device after a PIN entry, and
this API returns a verified identity or an assembled qualified signature. CAN
and PIN never reach this API - they are consumed by the card stack on the
client device.

Card-only by design (contracts v1.4.0). The two methods are
`physical` (a smart-card reader) and `nfc` (tapping the card to a phone).
Remote methods are deliberately not offered here: the v1.3 Smart-ID and
Mobile-ID passthrough was withdrawn in v1.4 before any provider was entitled
to it. For hosted remote-method ceremonies with delivery and reminders, use
the separate Tvarka Sign developer API at https://sign-api.tvarka.pro/docs.

Authentication ceremony: POST /v1/auth/requests (HTTP Basic) returns a scoped
clientToken; POST /v1/auth/{requestId}/certificate submits the card's
authentication certificate and returns the exact data-to-be-signed plus a
single-use operationToken; POST /v1/auth/{requestId}/complete submits the raw
card signature and returns the verified identity, optionally as an assertion
JWT verifiable against /.well-known/atk-jwks.json. This is proof of possession
plus PIN, not a qualified signature.

Signing ceremony: the same three phases under /v1/sign/*, producing PAdES,
ASiC-E, ADOC or detached CAdES (`raw`) with a qualified timestamp. Completion
is synchronous; an advisory validation axis settles separately and never
reverses a completed signature.

Trust services: POST /v1/validation validates an existing signed document,
POST /v1/timestamp adds qualified timestamps to untimestamped XAdES, and
POST /v1/archive upgrades PAdES B-T to B-LT.

Verify it yourself: the API returns the challenge nonce and the card
certificate, so a relying party can re-derive the data-to-be-signed from its
own audience and check the signature against the certificate without taking
Tvarka's word for the result.

Two tiers, one API. Authentication alone is the free tier, zero-rated for
national services registered as providers. Signing and the trust services are
paid. GDPR erasure is exposed as POST /v1/erasure and a per-request delete;
terminal requests are purged on a per-provider retention schedule.

Sandbox: a provider issued with environment=sandbox gets the identical API
against Tvarka-issued test cards and is never billed. A developer holding a
real Lithuanian eID can use a sandbox key today for authentication and PAdES.

Base URL: https://atk.tvarka.pro/v1
Contract: https://atk.tvarka.pro/openapi.json (also .yaml; specialist
  contracts at /openapi/auth.yaml and /openapi/sign.yaml)
Catalog: https://atk.tvarka.pro/apis.json
Docs: https://atk.tvarka.pro/docs/
Quickstart: https://atk.tvarka.pro/docs/quickstart/
Try it: https://atk.tvarka.pro/docs/try/
Test data: https://atk.tvarka.pro/docs/test-data/
SDKs: https://atk.tvarka.pro/docs/sdks/ (Python and web source bundles)
Postman: https://atk.tvarka.pro/postman/auth.json and /postman/sign.json
Pricing: https://atk.tvarka.pro/docs/pricing/
Lifecycle and retention: https://atk.tvarka.pro/docs/lifecycle/
Status: https://atk.tvarka.pro/status/ (JSON at /status.json, Atom feed at
  /status/feed.xml)
Auth: HTTP Basic keyId:keySecret for the provider backend; a scoped bearer
  clientToken for the card-driving client.
Webhooks: HMAC-signed terminal and validation events.
Access requests: https://atk.tvarka.pro/docs/access/ (a sandbox key costs
  nothing) or info@tvarka.pro
Price: EUR 0.07 plus VAT per successful operation. No subscription and no
  monthly minimum.

Operated from Lithuania. Tvarka is a software provider, not a qualified trust
service provider: the card is the secure signature-creation device, the
qualified certificates are Lithuanian state PKI, and qualified timestamps come
from a qualified timestamping authority.