eID-API-Integrationsleitfaden: Muster, Code und Sicherheit

Zuletzt geprüft: 5. Oktober 2026 · Keine Rechtsberatung

Dieser Code-orientierte Leitfaden richtet sich an Entwickler, die nationale eIDs in das Onboarding einbinden.

So funktioniert eine eID-API: fünf Interaktionsmuster

Ihr System ist der vertrauende Beteiligte (RP). Es sieht nie das Identifizierungsmittel selbst, nur eine signierte Antwort über die Person.

Manche Systeme liegen hinter einem öffentlichen Gateway: TARA in Estland ist ein Authorization-Code-Gateway vor der ID-Karte, Smart-ID, Mobile-ID und EU-eIDs.^[7] Unter eID-Systeme nach Land sehen Sie, welches Muster jedes System nutzt.

Was Sie selbst bauen und was ein Anbieter übernimmt

Der Zugang kommt vor dem Code. In Dänemark muss jeder Diensteanbieter über einen zertifizierten MitID-Broker gehen.^[12] In Schweden kaufen Sie BankID bei einer Bank oder einem Händler und bestellen ein Zertifikat für vertrauende Beteiligte.^[15] In Deutschland betreiben Sie einen eigenen eID-Server, nutzen einen gehosteten eID-Service mit eigenem Zertifikat oder nutzen einen Identifizierungsdienst und halten selbst kein Zertifikat.^[13] Für die EUDI-Wallet muss sich ein vertrauender Beteiligter in dem Mitgliedstaat registrieren, in dem er niedergelassen ist.^[1]

Für die meisten nordischen und baltischen Verfahren gibt es zertifizierte Broker. Gehen Sie bei einem einzelnen Verfahren mit hohem Volumen direkt; nutzen Sie eine API, wenn Nutzer aus mehreren Ländern kommen.

Der Weiterleitungsablauf Schritt für Schritt

Das ist der OIDC Authorization Code Flow. Ihr Backend leitet den Browser mit einem zufälligen state und nonce weiter, tauscht dann den zurückgegebenen Code gegen ein ID-Token und prüft es.

Eine Anmeldung per Weiterleitung. Broker und Gateways fügen in Schritt 2 Zwischenstationen hinzu, aber keine neuen Schritte für Sie.

Die Prüfung nach Schritt 5 ist am wichtigsten. Laut der ID-porten-Dokumentation von Digdir „MUSS der Client prüfen, dass das Sicherheitsniveau (acr) ausreichend hoch ist“.^[5] Verstehen Sie acr als das Vertrauensniveau (LoA), das das System zusichert, und lehnen Sie alles unterhalb Ihrer Richtlinie ab.

Der App-Push-Ablauf mit Vergleichscode

Bei Smart-ID und Mobile-ID verlässt der Ablauf Ihre Seite nie. Der Nutzer gibt einen persönlichen Identifikationscode ein (Mobile-ID fragt zusätzlich die Telefonnummer ab), Ihre Seite zeigt einen kurzen Code an, und derselbe Code erscheint in der App. Der Nutzer bestätigt mit der PIN auf dem Telefon nur, wenn die Codes übereinstimmen.^[20] Smart-ID kann auch drei Codes anzeigen und den Nutzer den richtigen auswählen lassen.^[10]

BankID Sweden folgt demselben Muster, nur mit einem QR-Code statt eines eingetippten Codes: Der Nutzer öffnet die App auf demselben Gerät mit einem Autostart-Token oder scannt einen animierten QR-Code, der auf dem anderen Gerät angezeigt wird. Ihr Backend fragt /collect ab, bis der Auftrag abgeschlossen ist. Der abgeschlossene Auftrag enthält die Personennummer, den Namen, den Vornamen und den Nachnamen sowie Geräte-, Signatur- und optionale Risikofelder.^[8] Smart-ID+ stellt Smart-ID auf dieses Modell um (dynamischer QR-Code am Desktop, App-to-App auf dem Smartphone). Nutzer tippen damit keinen persönlichen Code mehr auf einer Website ein.^[11]

Eine Anmeldung mit Smart-ID oder Mobile-ID in der Reihenfolge, die der Nutzer sieht: persönlicher Code, Vergleichscode auf Ihrer Seite, derselbe Code in der App, dann die PIN.^[20] In der QR-Variante von BankID entfällt Schritt 1, und Schritt 2 zeigt einen QR-Code.

Karte und NFC sowie die EUDI-Wallet über OpenID4VP

Beim deutschen Personalausweis hält der Nutzer die Karte an ein NFC-fähiges Smartphone mit der AusweisApp. Bevor die PIN eingegeben wird, muss die App nach dem Gesetz den Namen und die Anschrift des Diensteanbieters sowie die angefragten Datenkategorien anzeigen. Übermittelt werden nur diese Kategorien.^[14]

Laut der OpenID Foundation ist OpenID4VP 1.0 eine finale Spezifikation.^[16] Das Architecture and Reference Framework (ARF) nennt für die Fernvorlage OpenID4VP über Weiterleitungen und benutzerdefinierte URI-Schemata wie openid4vp://, OpenID4VP über die W3C Digital Credentials API oder ISO/IEC 18013-7 über diese API.^[2][17] Bevor die Wallet etwas teilt, authentifiziert sie Ihr Zugangszertifikat, prüft, dass Sie nicht mehr Attribute anfragen, als Sie registriert haben, und lässt den Nutzer jedes einzelne freigeben.^[2] Das Lichtbild wird in den Personenidentifizierungsdaten (PID) erst ab dem 11. August 2028 verpflichtend, außer der Nutzer lehnt dies ausdrücklich ab.^[18]

1. 23. Juli 2026ARF v3.0.0Aktuelle Version des Wallet-Rahmenwerks.
2. 24. Dezember 2026Wallets fälligJeder Mitgliedstaat stellt mindestens eine Wallet bereit.
3. 24. Dezember 2027AkzeptanzPrivate vertrauende Beteiligte, die gesetzlich oder vertraglich zu einer starken Nutzerauthentifizierung verpflichtet sind, akzeptieren sie auf Wunsch des Nutzers. Kleinst- und Kleinunternehmen sind ausgenommen.
4. 11. August 2028LichtbildDas Lichtbild in den PID wird verpflichtend, sofern der Nutzer dies nicht ablehnt.

Termine der EUDI-Wallet, die eine Roadmap für eine eID-API prägen.^[1][2][18]

Der Leitfaden zur EUDI-Wallet behandelt die Registrierung als vertrauender Beteiligter und den Umsetzungsstand nach Land.

Fehler, Fallbacks und erneute Versuche

Eine Anmeldung endet abgeschlossen, abgebrochen, mit Zeitüberschreitung oder fehlgeschlagen. Behandeln Sie die letzten drei Fälle gleich und legen Sie pro Land fest, was danach passiert.

Wiederholen Sie eine abgebrochene Anmeldung nie automatisch. Gestalten Sie den Callback idempotent, damit ein Neuladen oder ein doppeltes Ereignis nicht zwei Konten eröffnen kann. Halten Sie einen Weg für Personen ohne eID offen, in der Regel ein Ausweisdokument mit NFC-Chip-Auslesung, Liveness-Prüfung und Gesichtsabgleich. NFC-eID-Verifizierung und Chipsicherheit beschreibt diesen Weg.

Sicherheits-Checkliste für eine eID-API-Integration

• Erzeugen Sie für jede Anmeldung einen neuen state und nonce und weisen Sie einen Callback zurück, der nicht dazu passt.
• Prüfen Sie die Signatur jedes Tokens oder Ergebnisses, bevor Sie auch nur ein einziges Attribut lesen.
• Prüfen Sie das Vertrauensniveau im Ergebnis, nicht nur in der Anfrage.^[5]
• Verlangen Sie das Vertrauensniveau ‚substanziell‘ oder ‚hoch‘, wenn der eID-Weg der AMLR für Sie gilt.^[3]
• Erfassen Sie die eID-PIN nie auf Ihrer Seite; sie gehört in die App des jeweiligen Systems.^[20]
• Bevorzugen Sie bei geräteübergreifenden Anmeldungen einen QR-Code oder einen App-to-App-Start statt eingetippter Codes.^[11]
• Fordern Sie nur die Attribute an, die Sie registriert haben und benötigen.^[1]
• Prüfen Sie Webhook-Signaturen und Zeitstempel, bevor Sie einem Ergebnis vertrauen.

Der rechtliche Anker ist die Geldwäscheverordnung (AMLR), die ab dem 10. Juli 2027 gilt: Artikel 22(6)(b) lässt „elektronische Identifizierungsmittel, die die Anforderungen der Verordnung (EU) Nr. 910/2014 in Bezug auf die Vertrauensniveaus ‚substanziell‘ oder ‚hoch‘ erfüllen“ zu.^[3] Nicht jedes System ist notifiziert: MitID steht auf der EU-Liste der notifizierten Systeme, Smart-ID nicht.^[4]

Wie Didit bei der eID-API-Integration hilft

Didit bündelt fünf live verfügbare eIDs hinter einer Session-API (MitID, BankID Sweden, Finnish Trust Network, Smart-ID und Mobile-ID, in sieben Ländern), mit einem Dokumentenweg im selben Workflow. Weitere Systeme stehen auf Didits Roadmap, und die Akzeptanz der EUDI-Wallet folgt demnächst. Didit fragt nie nach der PIN. Mehr dazu auf der Seite Digitale ID-Wallets und in der Wallet-Dokumentation.^[19]

Live verfügbare eIDs pro Land aktivieren

In der Konsole: Workflows, Schritt ID Verification, Countries, „Wallets accepted“. Über die API nimmt die Funktion ID Verification (OCR) ein methods-Objekt entgegen, dessen Schlüssel ISO-3166-1-alpha-3-Ländercodes sind, gesendet mit POST /v3/workflows/. Das dokumentierte Fragment für Dänemark:^[21]

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

Und für Estland, mit Akzeptanz beider telefonbasierten eIDs:^[20]

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

providers ist eine Zulassungsliste, keine Rangfolge. on_failure ist fallback_to_document oder decline. Eine Wallet, die in Ihrer Umgebung nicht verfügbar ist, lässt das gesamte Speichern scheitern. Lesen Sie daher zuerst den Katalog.^[21]

Session erstellen und Ergebnis auslesen

POST /v3/session/ mit Ihrer workflow_id (und optional vendor_data und einem callback) liefert session_id, url und session_token zurück. Öffnen Sie die URL oder nutzen Sie das SDK.^[24] Das Ergebnis kommt per Webhook oder über GET /v3/session/{id}/decision/, mit verification_method: "wallet", assurance: "cryptographic" und einem wallet_verification-Objekt.^[19]

Ein niedrigeres Vertrauensniveau als das angeforderte lässt die Anmeldung scheitern. Abgerechnet werden nur abgeschlossene Anmeldungen.^[19] Preise: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhooks und Sandbox

Prüfen Sie X-Signature-V2 mit dem Secret Ihres Ziels, lehnen Sie einen X-Timestamp ab, der älter als 300 Sekunden ist, und verwenden Sie event_id als Idempotenzschlüssel. Eine fehlgeschlagene Zustellung wird bis zu zweimal wiederholt.^[22] Eine Sandbox-Anwendung kann jede Wallet aktivieren, genehmigt ohne echte Anmeldung und bietet wallet_cancelled, wallet_timeout und wallet_provider_error, damit Sie Ihren Fallback testen können.^[23]

Häufig gestellte Fragen

Quellen

1. Verordnung (EU) 2024/1183 (eIDAS 2), EUR-Lex, Amtsblatt vom 30. April 2024, Artikel 5a, 5b und 5f.
2. Architecture and Reference Framework v3.0.0, EUDI-Wallet-Projekt der Europäischen Kommission, veröffentlicht am 23. Juli 2026, Abschnitte 4.4.3, 5.7.1 und 6.6.3.
3. Verordnung (EU) 2024/1624 (AMLR), EUR-Lex, Artikel 22(6).
4. Überblick über vorab notifizierte und notifizierte eID-Systeme nach eIDAS, Europäische Kommission, abgerufen am 5. Oktober 2026.
5. ID-porten ID-Token, norwegische Digitalisierungsbehörde (Digdir).
6. Anbindung mit OpenID Connect, Entwicklerdokumentation von ID Austria.
7. Technische Spezifikation von TARA, estnische Behörde für Informationssysteme (RIA).
8. Auth and sign: collect, Entwicklerdokumentation von BankID.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3. Juli 2019 (Sekundärquelle).
10. Warum sehe ich manchmal einen Bestätigungscode und manchmal drei, Smart-ID.
11. Wie schützt mich das neue Smart-ID vor Betrug, Smart-ID.
12. MitID-Broker, dänische Agentur für Digitalisierung.
13. Diensteanbieter werden, AusweisApp, Bundesregierung.
14. § 18 Personalausweisgesetz (PAuswG), Gesetze im Internet.
15. Ihr Unternehmen an BankID anbinden, BankID.
16. Finale Spezifikation von OpenID for Verifiable Presentations 1.0 verabschiedet, OpenID Foundation.
17. Digital Credentials, W3C.
18. Durchführungsverordnung (EU) 2026/1731 der Kommission, EUR-Lex, Lichtbild in der PID ab dem 11. August 2028.
19. Digitale ID-Wallets, Didit-Dokumentation.
20. Integration von Smart-ID und Mobile-ID, Didit-Dokumentation.
21. Feature-Konfigurationen für Workflows, Didit-Dokumentation.
22. Webhooks, Didit-Dokumentation.
23. Sandbox und Testdaten, Didit-Dokumentation.
24. Schnellstart, Didit-Dokumentation.

Alle nationalen eIDs mit ihrem Niveau und ihrem Status finden Sie auf der Seite zur eID-Verifizierung.