eID API integration guide: patterns, code and security

Last reviewed: 5 October 2026 · Not legal advice

This code-first guide is for engineers adding national eIDs to onboarding.

How an eID API works: five interaction patterns

Your system is the relying party (RP). It never sees the credential itself, only a signed answer about the person.

Some schemes sit behind a public gateway: Estonia's TARA is an authorization code gateway in front of the ID card, Smart-ID, Mobile-ID and EU eIDs.^[7] See eID schemes by country for which pattern each scheme uses.

What you build and what a provider handles

Access comes before code. In Denmark every service provider must go through a certified MitID broker.^[12] In Sweden you buy BankID from a bank or a retailer and order a relying-party certificate.^[15] In Germany you run your own eID server, use a hosted eID service with your own certificate, or use an identification service and hold no certificate yourself.^[13] For the EUDI Wallet, a relying party must register in the Member State where it is established.^[1]

Certified brokers exist for most Nordic and Baltic schemes. Go direct for one scheme at high volume; use one API when users come from several countries.

The redirect flow, step by step

This is the OIDC authorization code flow. Your backend sends the browser out with a random state and nonce, then swaps the returned code for an ID token and checks it.

A redirect sign-in. Brokers and gateways add hops in step 2, not new steps for you.

The check after step 5 matters most. According to Digdir's ID-porten documentation, the client "MUST validate that the security level (acr) is sufficiently high".^[5] Read acr as the level of assurance (LoA) the scheme asserts, and refuse anything below your policy.

The app-push flow with a comparison code

Smart-ID and Mobile-ID never leave your page. The user types a personal identification code (Mobile-ID also asks for the phone number), your page shows a short code, and the same code appears in the app. The user approves with the PIN on the phone only when the codes match.^[20] Smart-ID can also show three codes and ask the user to pick the right one.^[10]

BankID Sweden is the same shape with a QR instead of a typed code: the user opens the app on the same device with an autostart token, or scans an animated QR shown on the other device, and your backend polls /collect until the order completes. The completed order carries the personal number, name, given name and surname, plus device, signature and optional risk fields.^[8] Smart-ID+ moves Smart-ID to this model (dynamic QR on desktop, app-to-app on mobile), so users no longer type a personal code on a website.^[11]

A Smart-ID or Mobile-ID sign-in, in the order the user sees it: personal code, comparison code on your page, the same code in the app, then the PIN.^[20] In the BankID QR variant, step 1 disappears and step 2 shows a QR code.

Card and NFC, and the EUDI Wallet over OpenID4VP

With the German eID card, the user holds the card to an NFC phone in the AusweisApp. Before the PIN is typed, the law requires the app to show the provider's name, address and the data categories requested, and only those categories are sent.^[14]

According to the OpenID Foundation, OpenID4VP 1.0 is a final specification.^[16] The Architecture and Reference Framework (ARF) lists remote presentation as OpenID4VP over redirects and custom URI schemes such as openid4vp://, OpenID4VP over the W3C Digital Credentials API, or ISO/IEC 18013-7 over that API.^[2][17] Before sharing anything, the wallet authenticates your access certificate, checks you do not ask for more attributes than you registered, and lets the user approve each one.^[2] The portrait only becomes mandatory in the person identification data (PID) from 11 August 2028, except where the user explicitly opts out.^[18]

1. 23 July 2026ARF v3.0.0Current version of the wallet framework.
2. 24 December 2026Wallets dueEach Member State offers at least one wallet.
3. 24 December 2027AcceptancePrivate relying parties required by law or contract to use strong user authentication accept it at the user's request. Micro and small enterprises are exempt.
4. 11 August 2028PortraitThe PID portrait becomes mandatory unless the user opts out.

EUDI Wallet dates that shape an eID API roadmap.^[1][2][18]

The EUDI Wallet guide covers relying-party registration and readiness by country.

Errors, fallbacks and retries

A sign-in ends completed, cancelled, timed out or failed. Handle the last three alike, and decide per country what happens next.

Never retry a cancelled sign-in automatically. Make the callback idempotent, so a refresh or a duplicate event cannot open two accounts. Keep a route for people with no eID, usually an identity document with NFC chip reading, liveness and face match. NFC eID verification and chip security covers that route.

Security checklist for an eID API integration

• Generate a fresh state and nonce per sign-in and reject a callback that does not match them.
• Verify the signature of every token or result before reading a single attribute.
• Check the level of assurance on the result, not only in the request.^[5]
• Require substantial or high where the AMLR eID route applies to you.^[3]
• Never collect the eID PIN on your page; it belongs in the scheme's app.^[20]
• Prefer QR or app-to-app launch over typed codes for cross-device sign-ins.^[11]
• Request only the attributes you registered and need.^[1]
• Verify webhook signatures and timestamps before you trust a result.

The legal anchor is the Anti-Money Laundering Regulation (AMLR), applying from 10 July 2027: Article 22(6)(b) allows "electronic identification means which meet the requirements of Regulation (EU) No 910/2014 with regard to the assurance levels 'substantial' or 'high'".^[3] Not every scheme is notified: MitID is on the EU list of notified schemes, Smart-ID is not.^[4]

How Didit helps with eID API integration

Didit puts five live eIDs behind one session API (MitID, BankID Sweden, Finnish Trust Network, Smart-ID and Mobile-ID, in seven countries), with a document route in the same workflow. More schemes are on Didit's roadmap, and EUDI Wallet acceptance is coming soon. Didit never asks for the PIN. More on the digital ID wallets page and in the wallet documentation.^[19]

Turn on live eIDs per country

In the console: Workflows, the ID Verification step, Countries, "Wallets accepted". Over the API, the ID Verification feature (OCR) takes a methods object keyed by ISO 3166-1 alpha-3 country code, sent with POST /v3/workflows/. The documented fragment for Denmark:^[21]

{ "feature": "OCR", "config": { "methods": { "DNK": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" } } } } }

And for Estonia, accepting both phone-based eIDs:^[20]

{ "EST": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["smart_id", "mobile_id"], "on_failure": "fallback_to_document" } } }

providers is an accept-list, not a ranking. on_failure is fallback_to_document or decline. A wallet that is not available in your environment rejects the whole save, so read the catalog first.^[21]

Create a session and read the result

POST /v3/session/ with your workflow_id (and optionally vendor_data and a callback) returns session_id, url and session_token. Open the URL or use the SDK.^[24] The result arrives by webhook or GET /v3/session/{id}/decision/, with verification_method: "wallet", assurance: "cryptographic" and a wallet_verification object.^[19]

A weaker level than requested fails the sign-in. Only completed sign-ins are billed.^[19] Prices: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhooks and sandbox

Verify X-Signature-V2 with your destination secret, reject an X-Timestamp older than 300 seconds, and key idempotency on event_id; a failed delivery is retried up to two times.^[22] A sandbox application can enable every wallet, approves without a real sign-in, and offers wallet_cancelled, wallet_timeout and wallet_provider_error to test your fallback.^[23]

Frequently asked questions

Sources

1. Regulation (EU) 2024/1183 (eIDAS 2), EUR-Lex, Official Journal of 30 April 2024, Articles 5a, 5b and 5f.
2. Architecture and Reference Framework v3.0.0, European Commission EUDI Wallet project, released 23 July 2026, sections 4.4.3, 5.7.1 and 6.6.3.
3. Regulation (EU) 2024/1624 (AMLR), EUR-Lex, Article 22(6).
4. Overview of pre-notified and notified eID schemes under eIDAS, European Commission, read 5 October 2026.
5. ID-porten ID token, Norwegian Digitalisation Agency (Digdir).
6. Anbindung mit OpenID Connect, ID Austria developer documentation.
7. TARA technical specification, Estonian Information System Authority (RIA).
8. Auth and sign: collect, BankID developer documentation.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3 July 2019 (secondary).
10. Why do I sometimes see one confirmation code and sometimes three, Smart-ID.
11. How does the new Smart-ID protect me from fraud, Smart-ID.
12. MitID brokers, Danish Agency for Digital Government.
13. Become a service provider, AusweisApp, German federal government.
14. Section 18 of the Passport and ID Card Act (PAuswG), Gesetze im Internet.
15. Connect your business to BankID, BankID.
16. OpenID for Verifiable Presentations 1.0 final specification approved, OpenID Foundation.
17. Digital Credentials, W3C.
18. Commission Implementing Regulation (EU) 2026/1731, EUR-Lex, portrait in the PID from 11 August 2028.
19. Digital ID wallets, Didit documentation.
20. Smart-ID and Mobile-ID integration, Didit documentation.
21. Workflow feature configs, Didit documentation.
22. Webhooks, Didit documentation.
23. Sandbox and test data, Didit documentation.
24. Quick start, Didit documentation.

See every national eID, its level and its status on the eID verification page.