# info.summary
Lithuanian eID authentication, qualified signing, validation and LTV services.

# info.description
The canonical ATK API contract. ATK physical-reader and NFC ceremonies are the primary authentication and signing methods. Smart-ID and Mobile-ID are optional server-side methods under the same request, polling, webhook and metering model. Start with the [five-minute quickstart](https://atk.tvarka.pro/docs/quickstart/) or use the specialist [authentication](https://atk.tvarka.pro/docs/auth/) and [signing](https://atk.tvarka.pro/docs/sign/) references.

# servers[].description
Production. Sandbox runs on the same host - provider credentials issued with
environment=sandbox get the identical API against test-card material and are never billed.

# tags[].description
The eID authentication ceremony (`/v1/auth/*`).

# tags[].description
NFC remote pairing - complete a request by tapping a card on a different device.

# tags[].description
Keys for verifying the optional `assertion` JWT.

# tags[].description
The QES signing ceremony (`/v1/sign/*`).

# tags[].description
Standalone advisory validation of signed artifacts.

# paths./auth/requests.post.description
Called by the provider's backend with HTTP Basic (`keyId:keySecret`). `audience` must be an
exact origin on the provider's allow-list. Physical requests return a short-lived `clientToken`;
NFC requests return a pairing hint; Smart-ID/Mobile-ID requests remain entirely server-side.

# paths./auth/requests.post.responses.202.description
Request created; awaiting the ATK client or remote user authorization.

# paths./auth/{requestId}/certificate.post.summary
Submit the card's authentication certificate; receive the DTBS + challenge

# paths./auth/{requestId}/certificate.post.description
Called by the client with `Authorization: Bearer <clientToken>`. The API validates the
certificate (chain, revocation, purpose = authentication, key usage), builds the canonical
challenge, and returns the exact `dtbs` the card must sign plus a single-use `operationToken`.
Physical/NFC only; server-side methods do not call this endpoint.

# paths./auth/{requestId}/complete.post.summary
Submit the raw card signature; receive the verified identity

# paths./auth/{requestId}/complete.post.description
Called by the client with `Authorization: Bearer <clientToken>` and the single-use
`operationToken` in the body. The API verifies the signature against the stored `dtbs` and the
certificate's public key, enforces the identity-swap guard, and returns the verified identity
(and the optional `assertion` JWT). Retry-safe: a repeat with the same tuple returns the same
result; a different signature/cert after the token is claimed is rejected.
Physical/NFC only; server-side methods complete asynchronously.

# paths./auth/{requestId}.get.description
Readable with the provider's Basic credentials for every method, or with the request's
`clientToken` for physical/NFC requests. Smart-ID/Mobile-ID providers poll this endpoint or
consume the terminal webhook.

# paths./auth/{requestId}/delete.post.description
Basic only, scoped to the caller's own provider. A non-terminal request is cancelled first,
then its document/result bytes + derived personal data are purged (exactly what the retention
job strips); a de-identified audit row remains. Idempotent.

# paths./erasure.post.summary
Bulk-erase the provider's terminal requests (GDPR)

# paths./erasure.post.description
Basic only. Purges document/result bytes + derived personal data of every TERMINAL,
not-yet-purged request of the calling provider (auth and sign alike); optional `before`
(ISO-8601) restricts to requests last updated before that moment. In-flight requests are
left untouched - erase them individually if intended.

# paths./auth/{requestId}/pairing.get.summary
Get a pairing token/QR to complete this request on a phone

# paths./auth/{requestId}/pairing.get.description
Only for `method:"nfc"`. Basic only - the integrator's server rotates the one-time token.
Returns a high-entropy, short-lived, one-claim pairing token and a deep link / QR the phone
scans. The phone then calls `/pairing/claim`, receives the request's `clientToken`, and
drives the same `/certificate` + `/complete` endpoints.

# paths./pairing/claim.post.summary
Claim a pairing token from the tapping phone

# paths./pairing/claim.post.description
No Basic auth - authorized solely by the high-entropy `pairingToken`. One-claim, rate-limited,
stored hashed. Returns the request's `clientToken` and a minimal `summary` (purpose + label
only, never document contents).

# paths./.well-known/atk-jwks.json.servers[].description
Host root - the JWKS lives outside the /v1 base path.

# paths./.well-known/atk-jwks.json.get.summary
JWKS for verifying the optional `assertion` JWT

# paths./.well-known/atk-jwks.json.get.description
Public keys (by `kid`) for the ES256 signer. Rotation keeps current + previous keys published so
in-flight assertions verify.

# paths./sign/requests.post.summary
Create a signing request (server-to-server)

# paths./sign/requests.post.description
HTTP Basic. Provide the document one of three ways - inline `document` (base64), an allow-listed
`documentRef`, or a bare `hash` (only for `format:"raw"`). Container formats
(pades/asice/adoc) require exactly one of `document` or `documentRef`. PAdES accepts an unsigned
or already-signed PDF; ASiC-E/ADOC accept either a PDF (Tvarka constructs a new single-payload
container) or an existing valid container, which is treated as an opaque whole and receives one
additional signature without payload or attachment edits. Physical requests return a client
token, NFC returns a pairing hint, and Smart-ID/Mobile-ID return a user verification code.
Remote methods are PAdES-only and stay server-side.

# paths./sign/requests.post.responses.202.description
Request created; awaiting the ATK client or remote user authorization.

# paths./sign/{requestId}/certificate.post.summary
Submit the card's signing certificate; receive the DTBS

# paths./sign/{requestId}/certificate.post.description
Bearer clientToken. The API validates the certificate (chain, revocation, purpose =
signing/content-commitment, qualified/QSCD evidence), prepares the format-specific DTBS (for
PAdES - the SHA-256 CAdES SignedAttributes digest; SHA-256 for both key curves), and returns
it + `operationToken`. Physical/NFC only.

# paths./sign/{requestId}/complete.post.summary
Submit the raw card signature; assemble the container

# paths./sign/{requestId}/complete.post.description
Bearer clientToken + single-use `operationToken`. Synchronous: the API verifies the signature
against the stored DTBS + cert, assembles + timestamps the AdES container inline, schedules
async validation, and returns `200 done` with `validation:{status:"pending"}` (or
`notApplicable` in sandbox/raw, or the internal ADOC verdict). `finalizing` is observable via
GET only if a crash wedges the request until the reaper releases it. Retry-safe; a transient
assembly failure returns a retryable 5xx with the operation released; one `atk.sign` charge
at `done`. Physical/NFC only; remote methods complete asynchronously.

# paths./sign/{requestId}/complete.post.responses.200.description
Done - container assembled + signature verified.

# paths./sign/{requestId}.get.summary
Poll status + validation axis; fetch the result

# paths./sign/{requestId}/document.get.description
Authorized by the provider's Basic credentials or a `downloadToken` query param.

# paths./sign/{requestId}/delete.post.description
Basic only, scoped to the caller's own provider. A non-terminal request is cancelled first,
then its document/container bytes + derived personal data are purged (exactly what the
retention job strips); a de-identified audit row remains. Idempotent. Bulk erasure lives on
the base API (`POST /v1/erasure`) and covers sign requests too.

# paths./sign/{requestId}/pairing.get.summary
Rotate and return the NFC pairing token for a sign request

# paths./validation.post.summary
Validate an existing signed document or container

# paths./validation.post.description
Paid-tier, Basic-authenticated synchronous service. SiVa backs PAdES/ASiC-E and can return
`passed`/`failed`. ADOC runs Tvarka's internal STRUCTURAL inspector, which performs no
cryptographic verification and therefore never returns `passed` - a structurally sound ADOC
yields `status: structural`. The verdict is advisory, not a regulatory conclusion. A
successful service call emits exactly one `atk.validate` event. `Idempotency-Key` makes network
retries replay the original response without a second event.

# paths./timestamp.post.summary
Add qualified timestamps to untimestamped XAdES signatures

# paths./timestamp.post.description
Paid-tier, Basic-authenticated synchronous service for ASiC-E and ADOC. Every XAdES signature
without SignatureTimeStamp receives an RFC 3161 token; existing timestamps are preserved. Emits
exactly one `atk.timestamp` event and returns a one-off output download token.

# paths./archive.post.summary
Upgrade a PAdES B-T signature to PAdES B-LT

# paths./archive.post.description
Paid-tier, Basic-authenticated synchronous service. Fresh signer and TSA revocation evidence is
collected and embedded as DSS/VRI; the OCSP freshness hard rule applies. Already-valid B-LT is
returned unchanged. Emits exactly one `atk.archive` event and returns a one-off download token.

# components.securitySchemes.basicAuth.description
Provider server-to-server credentials `keyId:keySecret`. Server-to-server only, also gated by the
provider's server IP allow-list. Never placed in a browser/mobile client.

# components.securitySchemes.clientToken.description
Short-lived, per-request JWT (`ES256`) minted at request creation, scoped
`{tenant, requestId, purpose, method, allowedOrigins}`. Safe to hand to a browser/mobile client:
it cannot create requests, read tenant data, or touch other requests. For browser clients the API
enforces `Origin` against `allowedOrigins` (rejects cross-origin replay).

# components.securitySchemes.downloadToken.description
One-off token returned with a completed sign result, for fetching the signed document.

# components.parameters.AuthRequestId.description
The `requestId` returned by `POST /auth/requests`.

# components.parameters.SignIdempotencyKey.description
1-255 visible characters; scoped to provider + service operation.

# components.schemas.AuthMethod.description
physical = desktop reader; nfc = phone tap; smart_id/mobile_id = server-side remote eID.

# components.schemas.AuthSignatureEncoding.description
Raw ECDSA signature encoding. P1363 = fixed-width r||s; DER = SEQUENCE(r, s). Informational - the server auto-detects and accepts either encoding regardless of this field.

# components.schemas.AuthCertSubject.description
Selected subject fields from the certificate. `serialNumber` holds `PNOLT-<personal code>`.

# components.schemas.AuthAuthRequestCreate.properties.audience.description
The relying-party origin (must be exactly on the provider's allow-list), e.g. https://www.epaslaugos.lt.

# components.schemas.AuthAuthRequestCreate.properties.personalCode.description
Required for Smart-ID and Mobile-ID; rejected for physical/NFC.

# components.schemas.AuthAuthRequestCreate.properties.phoneNumber.description
Required for Mobile-ID, rejected for every other method.

# components.schemas.AuthAuthRequestCreate.properties.message.description
Optional short message the client may display to the user.

# components.schemas.AuthAuthRequestCreate.properties.externalId.description
Provider's own correlation id (echoed back, deduped).

# components.schemas.AuthAuthRequestCreate.properties.webhookUrl.description
Optional public HTTPS webhook for the terminal status; private/non-global destinations are rejected.

# components.schemas.AuthAuthRequestCreated.description
Physical requests return `clientToken`; NFC requests return `pairing`; remote methods return neither.

# components.schemas.AuthAuthRequestCreated.properties.verificationCode.description
NFC anti-relay code, or the user verification code for Smart-ID/Mobile-ID.

# components.schemas.AuthAuthRequestCreated.properties.clientToken.description
Scoped bearer JWT for physical-card `/certificate` + `/complete`; absent for remote methods.

# components.schemas.AuthAuthRequestCreated.properties.nonce.description
Server-minted challenge nonce (see `Challenge`), so the provider backend can
re-derive `dtbs` and verify `sig` independently - no device relay needed.

# components.schemas.AuthCertificateSubmit.properties.certificate.description
Base64 DER of the card's **authentication** certificate.

# components.schemas.AuthCertificateChallenge.properties.dtbs.description
Base64 of the exact digest the card must sign (ECDSA prehashed). Built as the `atk-auth-v1`
construction - see `Challenge`.

# components.schemas.AuthCertificateChallenge.properties.operationToken.description
Single-use JWT bound to {tenant, requestId, purpose, certFp, dtbsHash}; the nonce is bound indirectly via dtbs. Returned at /complete.

# components.schemas.AuthCertificateChallenge.properties.cert.description
Echoes only the parsed `subject` (the client itself just submitted the DER).
The certificate DER is returned at `/complete` and on GET once done.

# components.schemas.AuthChallenge.description
Canonical `atk-auth-v1` anti-relay challenge. The server issues `nonce`; `dtbs` returned above =
`HASH( HASH(utf8(audience_origin)) || HASH(utf8(nonce)) )` with `HASH` matched to the auth-key
curve (P-256 -> SHA-256, P-384 -> SHA-384). Versioned - future profiles never reinterpret an
existing `dtbs`. This binding is what a relying party (e.g. ePaslaugos) audits.

# components.schemas.AuthChallenge.properties.nonce.description
Server-issued base64url challenge string (44-128 chars).

# components.schemas.AuthCompleteSubmit.properties.signature.description
Base64 raw card signature over `dtbs` (auth key).

# components.schemas.AuthAuthResult.properties.sig.description
The raw card signature over the audience-bound challenge, returned so the relying party can
verify identity independently of `assertion`. Audience-binding prevents cross-RP relay.

# components.schemas.AuthAuthResult.properties.assertion.description
Optional short-lived Tvarka-signed JWT (ES256), verifiable against the JWKS endpoint. Claims:
iss=atk.tvarka.pro, sub=<personal code>, aud=<audience>, iat, exp, jti, request_id
(binds the assertion to this ceremony), given_name, family_name, cert_fp,
authentication_method, amr. NOT OIDC.
Optional by contract - integrators may ignore it and verify the raw `sig` themselves.

# components.schemas.AuthAuthRequestState.properties.verificationCode.description
Present while a Smart-ID/Mobile-ID request is non-terminal.

# components.schemas.AuthAuthRequestState.properties.nonce.description
Server-minted challenge nonce (see `Challenge`) - enables independent `sig` verification from polling alone.

# components.schemas.AuthAuthRequestState.properties.cert.properties.der.description
Base64 DER, present once status == done.

# components.schemas.AuthPairingClaimRequest.properties.claimNonce.description
Optional; when the originating UI can pre-share it, binds the tap to the intended session.

# components.schemas.AuthPairingClaimResponse.properties.summary.description
Minimal display context {purpose, provider, audience, label, format?} - never document contents.

# components.schemas.AuthErrorCode.description
The full stable error-code catalog of the ATK API family (auth + sign + services);
each endpoint returns the subset that applies to it. By HTTP status:
400 invalid_json, missing_field, invalid_field, invalid_webhook_url, invalid_document_ref.
401 invalid_basic_credentials, invalid_client_token, client_token_expired,
operation_token_expired, invalid_download_token.
403 origin_not_allowed, ip_not_allowed, format_not_allowed, document_ref_host_not_allowed,
method_not_allowed, tenant_suspended, tier_forbidden.
404 request_not_found, pairing_not_found, document_not_ready.
409 request_terminal, operation_token_spent, identity_swap, idempotency_conflict,
service_in_progress, pairing_not_available, pairing_already_claimed.
410 pairing_expired. 413 document_too_large.
422 cert_invalid, untrusted_chain, cert_revoked, cert_expired, not_qualified,
cert_purpose_mismatch, signature_invalid, document_hash_mismatch, document_size_mismatch.
429 rate_limited. 500 assembly_failed. 502 document_ref_fetch_failed.
503 erasure_failed, pairing_service_unavailable, service_unavailable.
The catalog can grow in minor versions - fall back to HTTP status semantics
for codes you do not recognize.

# components.schemas.SignFormat.description
pades = signed PDF; asice/adoc = XAdES-T containers; raw = a detached CAdES package from
a bare hash (no container returned). Container formats require `document` or `documentRef`.

# components.schemas.SignDocumentRef.description
Backend-fetched document. Hard SSRF controls apply - HTTPS only, host allow-list, no
private/loopback/link-local, DNS-rebind protection, size cap enforced pre + mid stream, and the
fetched bytes are verified against `sha256`. `authorization` is used only for the fetch, never
logged or persisted.

# components.schemas.SignSignRequestCreate.description
ATK supports every listed format; Smart-ID/Mobile-ID support PAdES only.

# components.schemas.SignSignRequestCreated.description
Physical requests return `clientToken`; NFC returns `pairing`; remote methods return neither.

# components.schemas.SignSignRequestCreated.properties.verificationCode.description
NFC anti-relay code, or the user verification code for Smart-ID/Mobile-ID.

# components.schemas.SignSignCertificateSubmit.properties.certificate.description
Base64 DER of the card's signing certificate.

# components.schemas.SignSignCertificateChallenge.properties.dtbs.description
Base64 of the exact digest the card signs (e.g. for PAdES, the curve-matched digest of the CAdES SignedAttributes).

# components.schemas.SignSignCertificateChallenge.properties.signing.properties.signatureEncodingHints.description
Optional hint for how the card signature should be encoded before submission (P1363 vs DER).

# components.schemas.SignSignCompleteSubmit.properties.signature.description
Base64 raw card signature over `dtbs` (QES key).

# components.schemas.SignValidation.description
The advisory validation axis. Independent of `status`. See the two-axes note.

# components.schemas.SignValidation.properties.report.description
Optional pointer/id to the stored validation report.

# components.schemas.SignValidationServiceResult.properties.validation.properties.status.description
`passed`/`failed` come from SiVa (pades/asice). ADOC uses the internal
structural inspector and never returns `passed`; a structurally sound
container yields `structural`.

# components.schemas.SignSignResult.properties.sig.description
For `format:"raw"`, the detached signature package. Absent for container formats (download the container instead).

# components.schemas.SignSignResult.properties.downloadToken.description
One-off token for GET /sign/{id}/document.

# components.schemas.SignSignRequestState.properties.verificationCode.description
Present while a Smart-ID/Mobile-ID request is non-terminal.

# components.schemas.SignMethod.description
physical/NFC use card endpoints; smart_id/mobile_id complete server-side and support PAdES only.

# components.schemas.SignStatus.description
Non-terminal - pending/awaitingCard/awaitingCredentials/finalizing. Terminal success - done.
Terminal failure - cancelled/timeout/deviceError/pinBlocked/cardRemoved/certInvalid.
Validation failure is on the `validation` axis, NOT here.

# components.schemas.SignSignatureEncoding.description
Informational - the server auto-detects and accepts either encoding regardless of this field.

# components.schemas.SignErrorCode.description
The full stable error-code catalog of the ATK API family (auth + sign + services);
each endpoint returns the subset that applies to it. By HTTP status:
400 invalid_json, missing_field, invalid_field, invalid_webhook_url, invalid_document_ref.
401 invalid_basic_credentials, invalid_client_token, client_token_expired,
operation_token_expired, invalid_download_token.
403 origin_not_allowed, ip_not_allowed, format_not_allowed, document_ref_host_not_allowed,
method_not_allowed, tenant_suspended, tier_forbidden.
404 request_not_found, pairing_not_found, document_not_ready.
409 request_terminal, operation_token_spent, identity_swap, idempotency_conflict,
service_in_progress, pairing_not_available, pairing_already_claimed.
410 pairing_expired. 413 document_too_large.
422 cert_invalid, untrusted_chain, cert_revoked, cert_expired, not_qualified,
cert_purpose_mismatch, signature_invalid, document_hash_mismatch, document_size_mismatch.
429 rate_limited. 500 assembly_failed. 502 document_ref_fetch_failed.
503 erasure_failed, pairing_service_unavailable, service_unavailable.
The catalog can grow in minor versions - fall back to HTTP status semantics
for codes you do not recognize.

# components.responses.AuthUnauthorized.description
Missing/invalid credentials or client token.

# components.responses.AuthConflict.description
State/idempotency conflict (spent operation token, identity swap, terminal request).

# components.responses.AuthUnprocessable.description
Semantic reject (cert purpose/chain/revocation, dtbs mismatch, bad signature).

# components.responses.AuthServiceUnavailable.description
A required remote or erasure service is temporarily unavailable.

# components.responses.SignBadRequest.description
Malformed input (e.g. container format without document, hash without raw).

# components.responses.SignUnauthorized.description
Missing/invalid credentials or client token.

# components.responses.SignForbidden.description
Format not allowed / origin not allowed / tenant suspended.

# components.responses.SignConflict.description
Spent operation token, identity swap, terminal request, or idempotency conflict/in-progress operation.

# components.responses.SignUnprocessable.description
Cert purpose/chain/revocation/qualified reject, dtbs mismatch, bad signature, doc hash mismatch.

# components.responses.SignServiceUnavailable.description
Validation/TSA/revocation dependency failed transiently; retry with the same Idempotency-Key.

# externalDocs.description
Quickstart, SDKs, test data, pricing and lifecycle policy

# webhooks.signStatus.post.summary
Terminal status + validation-change callback (per-tenant HMAC-signed)

# webhooks.signStatus.post.description
Sent to the provider's `webhookUrl` on terminal `status` and on every `validation.status` change.
Headers - `X-Atk-Signature: sha256=<HMAC-SHA256(secret, raw-body)>`, `X-Atk-Idempotency-Key`, and
a timestamp. At-least-once; verify the MAC, reject stale timestamps, dedupe by idempotency key.