A Smart-ID integration in 2026 means SK ID Solutions' Relying Party API v3. Your server opens a session, shows a QR code on a computer or an app link on a phone, long-polls for the result, and verifies the certificate and signature before trusting anyone. Mobile-ID is the older phone-number flow with a four-digit verification code, and the Estonian ID-card works in browsers through Web eID.
SK says Smart-ID authentication usually takes developers one to two days, and signing up to a week where ID-card signing exists. The demo is free and needs no contract. Live, from 1 June 2026, Smart-ID and Mobile-ID both start at €0.109 per transaction excluding VAT, with €60 and €33 monthly minimums.
This guide, for product and engineering teams in Estonia and the wider Baltics, covers each flow, the screens to design, verification, signing, routes, testing and two autumn production changes. I checked it all against official documentation on 2 October 2026.
How Smart-ID, Mobile-ID and the ID-card compare
All three reach eIDAS level high and give qualified signatures; they differ in what users carry and what you build.
| Smart-ID | Mobile-ID | ID-card with Web eID | |
|---|---|---|---|
| User needs | The Smart-ID app, account renewed every 3 years | A Mobile-ID SIM from Telia, Elisa or Tele2 | ID-card or digi-ID, a card reader, Web eID |
| Countries | Estonia, Latvia, Lithuania | Estonia, Lithuania | Estonia |
| User types in your UI | Nothing (anonymous device link) | Phone number and ID code | Nothing |
| Assurance (RIA) | High, private scheme | High, national scheme | High, national scheme |
| Live price to you | From €0.109, €60 minimum | From €0.109, €33 minimum | No per-login fee on SK's list |
Smart-ID's site counted 543,906 users in Estonia, 981,192 in Latvia and 1,360,640 in Lithuania when I checked, and Web eID's architecture document says most of Estonia's 1.3 million citizens hold an ID-card. Offer all three in Estonia. Across the Baltics, Smart-ID is the common denominator: SK's Mobile-ID covers only Estonia and Lithuania, and Latvia uses eParaksts mobile.
How Smart-ID integration works in RP API v3
SK announced v3 as Smart-ID+ on 26 June 2025, live from July 2025. Versions 1 and 2 still work, but the new flows need app version 29 or later. TARA, the state login service, switched on 26 February 2026, so Estonians already know QR login.
The device-link sign-in, step by step
- Generate a fresh
rpChallengeof 32 to 64 random bytes, Base64-encode it and keep it in the server session. Base64-encode yourinteractionsonce (for exampledisplayTextAndPIN, up to 60 characters) and store that exact string. - POST to
/v3/authentication/device-link/anonymouswith your RP UUID, registered RP name, certificate level andACSP_V2, plus aninitialCallbackUrlfor app links. Send one request per attempt, even when showing a QR code and an app link together. - Keep the returned
sessionSecreton the server. - Rebuild QR links every second with a new
elapsedSeconds; build app links once, without it. - The app checks the link is genuine and fresh, shows your RP name and display text, and asks for PIN1.
- Long-poll
GET /v3/session/{sessionID}until COMPLETE, check the callback for app links, verify the response, then issue a new session ID.

import crypto from "node:crypto";
// Runs on your server once a second while the QR code is visible.
// ctx.scheme is "smart-id" in live and "smart-id-demo" in the demo.
function qrDeviceLink({ deviceLinkBase, sessionToken, sessionSecret }, ctx) {
const elapsed = Math.floor((Date.now() - ctx.responseReceivedAt) / 1000);
const unprotected = `${deviceLinkBase}?deviceLinkType=QR&elapsedSeconds=${elapsed}` +
`&sessionToken=${sessionToken}&sessionType=auth&version=1.0&lang=est`;
const payload = [ctx.scheme, "ACSP_V2", ctx.rpChallenge,
Buffer.from(ctx.rpName).toString("base64"), "", // brokeredRpName: empty
ctx.interactions, "", unprotected].join("|"); // initialCallbackUrl: empty for QR
const authCode = crypto.createHmac("sha256", Buffer.from(sessionSecret, "base64"))
.update(payload, "utf8").digest("base64url");
return `${unprotected}&authCode=${authCode}`;
}Smart-ID compares the link bit by bit: never URL-encode it, add a fragment, reorder parameters or compute authCodes ahead of time. Render the QR as SVG with error correction L or M, at 6 to 10 pixels per module on a computer.
Verification codes, notification flows and Mobile-ID
In the notification flow, the user types their ID code and Smart-ID pushes a request to every device on the account. Nothing links that push to your tab, so a phishing page could trigger one at the same moment. The verification code is the link: your page and the app show the same four digits, and the user must stop if they differ.
For login you compute the code from your challenge; for signing, the API returns it. The confirmationMessageAndVerificationCodeChoice interaction makes the user pick your code from three, and a wrong pick ends with WRONG_VC. Mobile-ID always needs a code, computed from your hash. Both are shown as four digits with leading zeros.
// Smart-ID: last 2 bytes of SHA-256 over the raw rpChallenge bytes, mod 10000
const sid = crypto.createHash("sha256").update(rpChallengeBytes).digest()
.readUInt16BE(30) % 10000;
// Mobile-ID: first 6 bits and last 7 bits of the 32-byte hash you send
const mid = ((hash[0] >> 2) << 7) | (hash[31] & 0x7f);Mobile-ID step by step
- The user enters a phone number (prefill +372) and ID code; check the checksum first.
- POST to
/authenticationwith both, a Base64hash,hashType,language(EST, ENG, RUS or LIT) and optionaldisplayText. - Show the code. The phone shows your RP name, text and code, then asks for PIN1.
- Long-poll
/authentication/session/{sessionId}, verify the signature over your hash, validate the certificate and rotate the session ID.
Display text allows 100 GSM-7 characters or 50 in UCS-2, which Estonian õ, š and ž need. Users get about two minutes before TIMEOUT. For signing, fetch the certificate first and let your container library add OCSP data, because Mobile-ID makes no OCSP request.
The Estonian ID-card in the browser with Web eID
Web eID, from Estonia's Information System Authority (RIA), replaced TLS client certificates, which skipped the PIN until the browser restarted. Your page loads web-eid.js, which talks to a browser extension and native app in Chrome, Edge, Firefox and Safari on Windows, macOS 14 or later and Ubuntu.
- Your server issues a single-use challenge nonce of at least 256 bits and stores it in the session.
webeid.authenticate(nonce)shows your origin, asks for consent and PIN1, and the card signshash(origin)+hash(challenge).- Your page POSTs the token with CSRF protection, and the server checks the certificate, OCSP status, nonce and signature.
Signing uses getSigningCertificate() and sign(), with your server building the container. Validation libraries exist for Java, .NET and PHP only, so Node.js and Python teams write the checks themselves or use a broker. RIA also documents a Web eID for Mobile protocol, using NFC and the RIA DigiDoc app; check its status before relying on it.
Polling, callbacks, errors and timeouts
Both APIs long-poll. Smart-ID's session endpoint takes timeoutMs from 1,000 to 120,000 (60,500 by default) and answers RUNNING when time runs out. Mobile-ID defaults to 10,000 ms, wants your HTTP timeout about 1,500 ms higher and forbids overlapping requests.
Smart-ID's callback URL is a redirect into a new tab, not a webhook. Add a random, single-use value to initialCallbackUrl, set the session cookie SameSite=Lax, and on return check that value, sessionSecretDigest and userChallengeVerifier. Brokers differ: eID Easy offers signature webhooks, Dokobit redirects back with a token you query, and Authentigate is standard OpenID Connect.
| Result | What the user should see |
|---|---|
| USERREFUSED, USERCANCELLED | "Sign-in was cancelled", with a retry button |
| TIMEOUT | "The request expired", with a fresh QR code or code |
| WRONG_VC | "Nothing was confirmed. Start again and pick the code shown here" |
| REQUIREDINTERACTIONNOTSUPPORTEDBY_APP | "Update your Smart-ID app" |
| HTTP 404 at start, NOTMIDCLIENT | Your usual neutral error, never "no account" |
| PHONEABSENT, DELIVERYERROR | "We could not reach your phone" |
| HTTP 580, SERVER_ERROR | "Smart-ID is not responding. Try again shortly" |
HTTP 480 means your client library is too old: alert your team, not the user.
Verifying the result: certificates, levels and eIDAS
SK's checklist before you trust a Smart-ID result:
- State COMPLETE, result OK, protocol ACSP_V2, and certificate, signature and result present.
- A chain to SK CA certificates you configure, with the system trust store off. The API sends only the user's certificate.
- OCSP from the AIA field, CRL as fallback. SK's OCSP responder certificates rotate every 30 days, so validate them and never pin them.
- Smart-ID policy OIDs, the right key usage, and a
certificateLevelthat meets your minimum. ADVANCED (Basic) accounts are for banks. - The ACSP_V2 payload rebuilt byte for byte, and the signature verified with the returned algorithm parameters.
- Identity from serialNumber (PNOEE-30001010004). Newer common names hold only names.
Both APIs add response fields over time, so ignore unknown ones.
eIDAS has three assurance levels: low, substantial and high. RIA lists the ID-card, digi-ID and Mobile-ID as national schemes at high, usable across the EU since 2018, and Smart-ID as a private scheme it assessed as high, valid until 23 November 2027. Smart-ID has been a qualified signature creation device since 8 November 2018, so qualified accounts give signatures equal to handwritten ones across the EU. Request the QSCD level when a flow must guarantee that.
Signing documents: ASiC-E, BDOC and the libraries
Smart-ID v3 signs a digest you send, so the container is your job. After a Smart-ID login, /v3/signature/certificate/{document-number} returns the signing certificate with no user action, and you start a signature session on that document number. Without a login, SK recommends linked signing: an anonymous device-link certificate choice, then /v3/signature/notification/linked/{document-number}. The app opens once and needs no code.
Build ASiC-E (.asice) with LT signatures, which carry a timestamp and OCSP data; it has been Estonia's default since 2019. Time-mark BDOC is finished for new signatures: SK's OCSP dropped it on 1 November 2023 and DigiDoc4j removed it in version 5.2.0, though old .bdoc files still validate. Use DigiDoc4j for Java (6.2.0, August 2026) or libdigidocpp for C++, C#, Java or Python (4.5.1, September 2026). SK requires that users can download what they signed.
At SK's entry tiers a direct signature costs €0.109, plus €0.036 for the timestamp and €0.024 for OCSP: €0.169 in all. The minimums add up to €105.60 a month (€60, €36 and €9.60) excluding VAT. DigiDoc4j can also use SK's free AIA OCSP responder, so ask SK which fits your volume.
Direct, Authentigate or a broker: choosing your route
| Route | What you build | Published price (ex VAT) |
|---|---|---|
| Direct to SK | Every screen, polling, verification, container, IP whitelisting and TLS pins | Smart-ID from €0.109 (€60 minimum), Mobile-ID from €0.109 (€33) |
| SK Authentigate: OpenID Connect for Smart-ID, Mobile-ID, ID-card, eParaksts | A standard OIDC client; login only | From €29 a month with 100 logins |
| Dokobit: hosted or embedded gateway, signing API | Redirect and status calls | A PDF price list I could not load |
| eID Easy: OAuth 2.0 login, signing API, webhooks | API or widget integration | Quote only |
| TARA (RIA) | Not open to startups | Government sector only |
Worked example: 1,000 Smart-ID and 200 Mobile-ID logins a month. Direct is €109 plus Mobile-ID's €33 minimum: €142. Authentigate Small is €49 for 500 plus 700 at €0.098: €117.60, ID-card included.
- List the jobs: login, step-up confirmation, signing, age checks.
- List your users' countries and the eIDs they hold.
- Price each route from the published lists at your volume.
- Match your stack: Smart-ID clients in Java and PHP, Web eID validation in Java, .NET and PHP.
- Decide who owns the screen: you, a hosted page or a widget.
My rule: login only, or no Java, PHP or .NET back end, means Authentigate or a broker. Qualified signing at volume or your own fraud controls means direct. Many countries or EU wallets means a broker. The integration is a small slice of the budget; my guide to web development costs in Estonia covers the rest.
A UX checklist for the sign-in screen
- Computer: QR only. Phone: "Open Smart-ID app" first, QR second. Tablet: QR first. Requesting the desktop site changes the user agent, so keep both reachable.
- Write "Smart-ID" exactly so, untranslated, with SK's official buttons.
- Refresh the QR every second, never show one older than 3 seconds, and after about 60 seconds warn "This session is about to expire".
- Use SK's wording: "Scan the QR code with Smart-ID app to continue" and "Finish authentication in Smart-ID app".
- Web2App returns in a new tab. In-app browsers, non-default iOS browsers and private mode break the cookie check: say "Please try again from your default browser".
- Write concrete display texts ("Signing document Contract.asice"), separate ones for website and helpdesk, and warnings for unknown browsers.
- Show codes large: "Check the code matches. If not, cancel".
- Mobile-ID: prefill +372, check the checksum, keep the code visible.
- ID-card: detect a missing Web eID extension; never ask for a PIN on your page.
- Design every state in the error table, then offer the signed file and an action history.
Testing, going live and the autumn 2026 changes
| Smart-ID demo | Mobile-ID demo | |
|---|---|---|
| Base URL | https://sid.demo.sk.ee/smart-id-rp/v3/ | https://tsp.demo.sk.ee/mid-api |
| RP UUID, name | 00000000-0000-4000-8000-000000000000, DEMO | 00000000-0000-0000-0000-000000000000, DEMO |
| Estonian success | Device link PNOEE-40404040009-MOCK-Q, push PNOEE-40504040001-DEM2-Q | +37269930366 with 51307149560 |
| Refusal, timeout | Push PNOEE-30403039917-MOCK-Q, PNOEE-30403039983-MOCK-Q | +37201100266 with 60001019950, +37266000266 with 50001018908 |
Test identities answer automatically. For device-link tests, post session values to SK's mock service, which also calls your callback URL; SK's demo apps on TestFlight and Google Play cover manual tests. Upload demo certificates to the demo OCSP first, and never use the demo for security testing.
- Build and test against the demo.
- Send SK your server IP addresses and a public service name. Generic names such as "login" are refused.
- Sign the agreement, adding OCSP and timestamping if you sign documents.
- Receive your RP UUID, then switch URLs, scheme name, CA certificates and pins to live.
SK applies a new Smart-ID TLS certificate on 6 October 2026 at 13:00 EEST and the current one expires on 11 October, so pin both. From 2 November 2026, both services' production endpoints accept only TLSAES256GCMSHA384 on TLS 1.3, and ECDHE or DHE RSA with AES-256-GCM-SHA384 on TLS 1.2. The demo already does, so test now.
Common mistakes to avoid
- Building authCodes in the browser, which leaks the session secret.
- Trusting the system certificate store, or missing SK ID Solutions EID-Q 2021E, which has issued Estonian Mobile-ID since 12 August 2024.
- Setting your HTTP timeout equal to
timeoutMs, so answers near the limit time out on your side. - Reusable callback URLs, or SameSite=Strict cookies that break Web2App returns.
- Telling users an ID code or phone number has no account.
- Starting new signing work on BDOC-TM instead of ASiC-E.
Frequently asked questions
How long does a Smart-ID integration take?
SK says developers report one to two days for Smart-ID authentication, and up to a week for signing when ID-card signing already exists. That is only the API work. Budget separately for screens and error states, certificate validation, demo testing and SK's agreement, which together usually take longer.
How much does Smart-ID cost for a business?
From 1 June 2026, SK's entry plan is €0.109 per authentication or signing request with a €60 monthly minimum, falling to €0.0106 at three million transactions a month. Mobile-ID starts at €0.109 with a €33 minimum. Prices exclude VAT, SK lists no setup fees, and timestamps and OCSP are billed separately.
Is Smart-ID API v2 being switched off?
SK has not announced an end date. Its FAQ says v1 and v2 keep working, while encouraging everyone to build the v3 device-link flows. The direction is clear: the state's own TARA service switched to Smart-ID+ in February 2026, and SK presents device links as its main defence against phishing.
Can I integrate Smart-ID with a Node.js or Python back end?
Yes. Both SK APIs are JSON over HTTPS, and SK's documentation shows samples in nine languages. SK's own client libraries cover Java and PHP, and it lists a third-party Node.js client for v3. The gaps are Web eID validation (Java, .NET and PHP only) and signing, where DigiDoc4j is Java and libdigidocpp offers Python bindings.
Why does the Smart-ID app say my QR code is invalid?
Usually the user's app is older than version 29, or your authCode differs from Smart-ID's. Check the scheme name (smart-id-demo in the demo), that the interactions string is byte for byte what you sent, that the RP name keeps its capitalisation, that the link is not URL-encoded, and that your server rebuilds it every second.
Will the EU Digital Identity Wallet replace Smart-ID?
Not overnight. The European Commission says member states must offer EU Digital Identity Wallets by the end of 2026, and service providers legally required to identify customers will have to accept them. Nothing I found says Smart-ID, Mobile-ID or the ID-card will be withdrawn, so treat wallets as an extra method; eID Easy already lists several.
My recommendation
Build Smart-ID first with v3 device links, then add Mobile-ID and the ID-card, and design the waiting and failure states before the polling code. For login only, price Authentigate against going direct. For qualified signing, choose your container library first, because it shapes the stack.
Building for Estonian users? See my approach to development for Tallinn startups.
Sources and method
I collected every figure on 2 October 2026 from the pages below. All prices are SK's list prices in euros excluding VAT, so no currency conversion was needed. Data is thin in four places: Dokobit's pricing PDF returned a rate-limit error, so I quote no Dokobit prices; eID Easy publishes none; SK gives no Smart-ID session lifetime beyond its 60-second QR guidance; and the Authentigate example is my reading of its price table.
- SK ID Solutions, Smart-ID RP API v3 documentation (version 3.2.3), checked 2 October 2026: introduction, endpoints, device links, authCode, notifications, callbacks, verification, API details, interactions, security, mock service, OpenAPI, environments, test accounts, demo, UX, FAQ, pinning, libraries
- SK ID Solutions, Mobile-ID REST API and wiki, checked 2 October 2026: API, environments, test numbers
- SK ID Solutions, price list valid from 1 June 2026, checked 2 October 2026: skidsolutions.eu
- SK ID Solutions news, 26 June 2025, 30 October 2023, 7 and 14 September 2026: Smart-ID+, OCSP, ciphers, certificate
- SK ID Solutions, Authentigate documentation, checked 2 October 2026: overview, specification, environments
- Smart-ID, public and business pages, checked 2 October 2026: user counts, integration, branding, QSCD, signing
- Information System Authority (RIA), Web eID, ria.ee and ID.ee pages, checked 2 October 2026: web-eid.eu, architecture, Web eID for Mobile, assurance levels, TARA, .bdoc and .asice, BDOC-TM ends, Mobile-ID operators
- Libraries on GitHub, release pages checked 2 October 2026: DigiDoc4j, libdigidocpp
- Brokers, checked 2 October 2026: Dokobit gateway docs, Dokobit API docs, eID Easy pricing, eID Easy docs
- European Commission, EU Digital Identity framework, updated 22 June 2026: digital-strategy.ec.europa.eu
Tags: Estonia, Smart-ID, Mobile-ID, Web eID, Authentication


