Guide d'intégration d'une API eID : modèles, code et sécurité

Dernière révision : 5 octobre 2026 · Ceci n'est pas un avis juridique

Ce guide axé sur le code s'adresse aux ingénieurs qui intègrent des eID nationales dans l'onboarding.

Fonctionnement d'une API eID : cinq modèles d'interaction

Votre système est la partie utilisatrice (RP). Il ne voit jamais l'identifiant lui-même, seulement une réponse signée concernant la personne.

Certains schémas passent par une passerelle publique : en Estonie, TARA est une passerelle à code d'autorisation placée devant la carte d'identité, Smart-ID, Mobile-ID et les eID de l'UE.^[7] Consultez les schémas eID par pays pour savoir quel modèle utilise chaque schéma.

Ce que vous développez et ce que gère un prestataire

L'accès passe avant le code. Au Danemark, tout fournisseur de services doit passer par un courtier MitID certifié.^[12] En Suède, vous achetez BankID auprès d'une banque ou d'un revendeur et vous commandez un certificat de partie utilisatrice.^[15] En Allemagne, vous exploitez votre propre serveur eID, vous utilisez un service eID hébergé avec votre propre certificat, ou vous passez par un service d'identification sans détenir vous-même de certificat.^[13] Pour le portefeuille EUDI, une partie utilisatrice doit s'enregistrer dans l'État membre où elle est établie.^[1]

Des courtiers certifiés existent pour la plupart des schémas nordiques et baltes. Passez en direct pour un seul schéma à fort volume ; utilisez une seule API lorsque les utilisateurs viennent de plusieurs pays.

Le flux par redirection, étape par étape

Il s'agit du flux du code d'autorisation OIDC. Votre backend redirige le navigateur avec un state et un nonce aléatoires, puis échange le code renvoyé contre un jeton d'identité (ID token) et le vérifie.

Une connexion par redirection. Les courtiers et les passerelles ajoutent des sauts à l'étape 2, pas de nouvelles étapes pour vous.

La vérification après l'étape 5 est la plus importante. Selon la documentation ID-porten de Digdir, le client « DOIT valider que le niveau de sécurité (acr) est suffisamment élevé ».^[5] Lisez acr comme le niveau de garantie (LoA) affirmé par le schéma, et refusez tout ce qui est inférieur à votre politique.

Le flux par notification push avec un code de comparaison

Avec Smart-ID et Mobile-ID, l'utilisateur ne quitte jamais votre page. Il saisit un code d'identification personnel (Mobile-ID demande aussi le numéro de téléphone), votre page affiche un code court, et le même code apparaît dans l'application. L'utilisateur valide avec le code PIN sur le téléphone uniquement si les codes correspondent.^[20] Smart-ID peut aussi afficher trois codes et demander à l'utilisateur de choisir le bon.^[10]

BankID Suède suit le même schéma, avec un QR code à la place d'un code saisi. L'utilisateur ouvre l'application sur le même appareil avec un jeton de démarrage automatique, ou scanne un QR code animé affiché sur l'autre appareil. Votre backend interroge /collect jusqu'à la fin de la commande. La commande terminée contient le numéro personnel, le nom, le prénom et le nom de famille, ainsi que des champs relatifs à l'appareil, à la signature et, en option, au risque.^[8] Smart-ID+ fait passer Smart-ID à ce modèle (QR code dynamique sur ordinateur, d'application à application sur mobile). Les utilisateurs n'ont donc plus à saisir de code personnel sur un site web.^[11]

Une connexion Smart-ID ou Mobile-ID, dans l'ordre où l'utilisateur la voit : code personnel, code de comparaison sur votre page, le même code dans l'application, puis le code PIN.^[20] Dans la variante BankID avec QR code, l'étape 1 disparaît et l'étape 2 affiche un QR code.

Carte et NFC, et le portefeuille EUDI via OpenID4VP

Avec la carte d'identité électronique allemande, l'utilisateur pose sa carte contre un téléphone NFC dans l'AusweisApp. Avant la saisie du code PIN, la loi impose à l'application d'afficher le nom et l'adresse du fournisseur ainsi que les catégories de données demandées. Seules ces catégories sont transmises.^[14]

Selon l'OpenID Foundation, OpenID4VP 1.0 est une spécification finale.^[16] L'Architecture and Reference Framework (ARF) prévoit la présentation à distance via OpenID4VP par redirections et schémas d'URI personnalisés tels que openid4vp://, via OpenID4VP sur la W3C Digital Credentials API, ou via ISO/IEC 18013-7 sur cette API.^[2][17] Avant tout partage, le portefeuille authentifie votre certificat d'accès, vérifie que vous ne demandez pas plus d'attributs que ceux que vous avez enregistrés, et permet à l'utilisateur d'approuver chacun d'eux.^[2] La photo ne devient obligatoire dans les données d'identification personnelle (PID) qu'à partir du 11 août 2028, sauf si l'utilisateur la refuse expressément.^[18]

1. 23 juillet 2026ARF v3.0.0Version actuelle du cadre du portefeuille.
2. 24 décembre 2026Échéance des portefeuillesChaque État membre propose au moins un portefeuille.
3. 24 décembre 2027AcceptationLes parties utilisatrices privées tenues, par la loi ou par contrat, d'utiliser une authentification forte de l'utilisateur l'acceptent à la demande de l'utilisateur. Les microentreprises et les petites entreprises en sont exemptées.
4. 11 août 2028PhotoLa photo du PID devient obligatoire, sauf refus de l'utilisateur.

Les dates du portefeuille EUDI qui structurent une feuille de route d'API eID.^[1][2][18]

Le guide du portefeuille EUDI traite de l'enregistrement des parties utilisatrices et de l'état de préparation par pays.

Erreurs, solutions de repli et nouvelles tentatives

Une connexion se termine par un succès, une annulation, un délai dépassé ou un échec. Traitez les trois derniers cas de la même manière, et décidez pays par pays de la suite.

Ne relancez jamais automatiquement une connexion annulée. Rendez le callback idempotent, pour qu'un rafraîchissement ou un événement en double ne puisse pas ouvrir deux comptes. Prévoyez un parcours pour les personnes sans eID, en général un document d'identité avec lecture de la puce NFC, détection du vivant et comparaison faciale. Vérification eID par NFC et sécurité de la puce présente ce parcours.

Liste de contrôle sécurité pour une intégration d'API eID

• Générez un state et un nonce nouveaux à chaque connexion et rejetez tout callback qui ne leur correspond pas.
• Vérifiez la signature de chaque jeton ou résultat avant de lire le moindre attribut.
• Contrôlez le niveau de garantie dans le résultat, pas seulement dans la requête.^[5]
• Exigez le niveau substantiel ou élevé lorsque la voie eID de l'AMLR s'applique à vous.^[3]
• Ne collectez jamais le code PIN de l'eID sur votre page. Il doit être saisi dans l'application du schéma.^[20]
• Préférez un lancement par QR code ou d'application à application plutôt que des codes saisis pour les connexions multi-appareils.^[11]
• Ne demandez que les attributs que vous avez enregistrés et dont vous avez besoin.^[1]
• Vérifiez les signatures et les horodatages des webhooks avant de vous fier à un résultat.

Le fondement juridique est le règlement anti-blanchiment (AMLR), applicable à compter du 10 juillet 2027 : l'article 22(6)(b) admet « des moyens d'identification électronique qui satisfont aux exigences du règlement (UE) n° 910/2014 en ce qui concerne les niveaux de garantie "substantiel" ou "élevé" ».^[3] Tous les schémas ne sont pas notifiés : MitID figure sur la liste européenne des schémas notifiés, Smart-ID n'y figure pas.^[4]

Comment Didit facilite l'intégration d'API eID

Didit réunit cinq eID en production derrière une seule API de session (MitID, BankID Suède, Finnish Trust Network, Smart-ID et Mobile-ID, dans sept pays), avec un parcours documentaire dans le même workflow. D'autres schémas figurent sur la feuille de route de Didit, et l'acceptation du portefeuille EUDI arrive bientôt. Didit ne demande jamais le code PIN. Plus d'informations sur la page portefeuilles d'identité numérique et dans la documentation des portefeuilles.^[19]

Activer les eID en production par pays

Dans la console : Workflows, l'étape ID Verification, Countries, « Wallets accepted ». Par l'API, la fonctionnalité ID Verification (OCR) accepte un objet methods indexé par code pays ISO 3166-1 alpha-3, envoyé avec POST /v3/workflows/. Le fragment documenté pour le Danemark :^[21]

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

Et pour l'Estonie, en acceptant les deux eID sur téléphone :^[20]

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

providers est une liste d'acceptation, pas un classement. on_failure vaut fallback_to_document ou decline. Un portefeuille qui n'est pas disponible dans votre environnement fait échouer tout l'enregistrement : consultez d'abord le catalogue.^[21]

Créer une session et lire le résultat

POST /v3/session/ avec votre workflow_id (et, en option, vendor_data et un callback) renvoie session_id, url et session_token. Ouvrez l'URL ou utilisez le SDK.^[24] Le résultat arrive par webhook ou via GET /v3/session/{id}/decision/, avec verification_method: "wallet", assurance: "cryptographic" et un objet wallet_verification.^[19]

Un niveau inférieur à celui demandé fait échouer la connexion. Seules les connexions abouties sont facturées.^[19] Tarifs : MitID, Finnish Trust Network $0.25 ; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhooks et sandbox

Vérifiez X-Signature-V2 avec le secret de votre destination, rejetez un X-Timestamp de plus de 300 secondes et basez l'idempotence sur event_id ; une livraison échouée est relancée jusqu'à deux fois.^[22] Une application sandbox peut activer tous les portefeuilles, approuve sans connexion réelle et propose wallet_cancelled, wallet_timeout et wallet_provider_error pour tester votre solution de repli.^[23]

Questions fréquentes

Sources

1. Règlement (UE) 2024/1183 (eIDAS 2), EUR-Lex, Journal officiel du 30 avril 2024, articles 5a, 5b et 5f.
2. Architecture and Reference Framework v3.0.0, projet de portefeuille EUDI de la Commission européenne, publié le 23 juillet 2026, sections 4.4.3, 5.7.1 et 6.6.3.
3. Règlement (UE) 2024/1624 (AMLR), EUR-Lex, article 22(6).
4. Aperçu des schémas eID prénotifiés et notifiés au titre d'eIDAS, Commission européenne, consulté le 5 octobre 2026.
5. Jeton d'identité ID-porten, Agence norvégienne du numérique (Digdir).
6. Anbindung mit OpenID Connect, documentation développeur d'ID Austria.
7. Spécification technique TARA, Autorité estonienne des systèmes d'information (RIA).
8. Auth and sign: collect, documentation développeur BankID.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3 juillet 2019 (source secondaire).
10. Pourquoi je vois parfois un code de confirmation et parfois trois, Smart-ID.
11. Comment le nouveau Smart-ID me protège contre la fraude, Smart-ID.
12. Courtiers MitID, Agence danoise pour l'administration numérique.
13. Devenir fournisseur de services, AusweisApp, gouvernement fédéral allemand.
14. Article 18 de la loi sur les passeports et les cartes d'identité (PAuswG), Gesetze im Internet.
15. Connecter votre entreprise à BankID, BankID.
16. Approbation de la spécification finale OpenID for Verifiable Presentations 1.0, OpenID Foundation.
17. Digital Credentials, W3C.
18. Règlement d'exécution (UE) 2026/1731 de la Commission, EUR-Lex, portrait dans les PID à compter du 11 août 2028.
19. Portefeuilles d'identité numérique, documentation Didit.
20. Intégration de Smart-ID et Mobile-ID, documentation Didit.
21. Configuration des fonctionnalités des workflows, documentation Didit.
22. Webhooks, documentation Didit.
23. Sandbox et données de test, documentation Didit.
24. Démarrage rapide, documentation Didit.

Consultez chaque eID nationale, son niveau et son statut sur la page Vérification eID.