Authentification KSeF 2.0 pour les développeurs : guide 2026

L’authentification KSeF 2.0 repose sur deux niveaux : vous prouvez d’abord une identité à l’aide d’une signature XAdES ou d’un ancien jeton KSeF, puis vous utilisez le jeton d’accès JWT renvoyé pour effectuer les appels protégés à l’API. Selon les règles en vigueur au 28 août 2026, l’authentification par jeton disparaît le 31 décembre 2026. Toute nouvelle intégration en production doit utiliser des certificats KSeF de type 1.

Ce guide a été vérifié le 28 août 2026 à partir de la documentation du ministère des Finances et du dépôt officiel de l’API KSeF. L’API continue d’évoluer : considérez donc le journal des modifications officiel comme une dépendance de production à part entière.

Comment fonctionne l’authentification KSeF 2.0 ?

KSeF 2.0 sépare l’authentification des sessions de facturation. Vous établissez d’abord qui effectue l’appel et dans quel contexte fiscal. Ce n’est qu’après avoir reçu un accessToken que vous pouvez ouvrir une session en ligne ou par lots, transmettre des factures, interroger les métadonnées ou récupérer les documents UPO.

Quatre types d’identifiants interviennent dans ce processus. Les confondre est à l’origine de la plupart des erreurs d’implémentation :

Le guide officiel de l’authentification décrit cette dernière paire comme des JWT délivrés au terme d’une opération asynchrone réussie. Le jeton d’accès doit figurer dans Authorization: Bearer .... Il ne s’agit pas du même objet que l’ancien jeton KSeF, valable à long terme.

Le contexte et l’identité sont distincts

Chaque connexion répond à deux questions :

1. Dans quel contexte cette session va-t-elle fonctionner ? Il s’agit généralement d’une entreprise identifiée par son NIP, mais KSeF prend également en charge d’autres identifiants de contexte.
2. Quelle identité s’authentifie ? Il peut s’agir de l’entreprise, d’une personne identifiée par son PESEL ou son NIP, ou encore d’une identité associée à l’empreinte d’un certificat.

KSeF vérifie que le sujet qui s’authentifie dispose d’au moins une autorisation active dans le contexte choisi. La possession d’un certificat valide ne suffit pas. Cette séparation est importante lorsqu’un cabinet comptable ou un salarié travaille pour plusieurs entreprises : un même certificat d’identité peut servir dans plusieurs contextes, tandis que les autorisations varient d’un contexte à l’autre.

Quelle méthode d’authentification KSeF choisir en 2026 ?

Pour une nouvelle intégration en production, utilisez XAdES avec un certificat d’authentification KSeF de type 1. Ne conservez la prise en charge des anciens jetons KSeF que comme solution transitoire pendant la migration. La réglementation actuellement en vigueur autorise cette méthode jusqu’au 31 décembre 2026, et les directives actuelles du ministère indiquent que les certificats restent valables à compter du 1ᵉʳ janvier 2027.

Cette échéance appelle toutefois une précision. En juin 2026, le ministère a proposé de prolonger les jetons KSeF avec une durée de validité plus courte et des mécanismes de renouvellement. À la date de vérification de cet article, il ne s’agit que d’une proposition soumise à consultation, et non d’une règle promulguée. Tant que la réglementation n’évolue pas, planifiez la migration en fonction de l’échéance juridiquement contraignante.

Cette distinction est directement issue du manuel KSeF 2.0 du ministère des Finances : un certificat porte une identité, mais aucune autorisation KSeF, tandis qu’un jeton KSeF porte un sous-ensemble d’autorisations et se limite à un seul contexte.

N’utilisez pas un certificat hors ligne pour l’authentification

KSeF délivre deux types de certificats destinés à des usages différents :

• Authentication signe la demande de connexion.
• Offline atteste l’authenticité de l’émetteur et l’intégrité de la facture dans un processus hors ligne.

Un certificat Offline ne peut pas authentifier les appels d’API. Le guide officiel des certificats met également en garde contre l’utilisation d’un certificat d’authentification pour signer les justificatifs de factures hors ligne. Stockez et étiquetez séparément les deux clés privées afin qu’un déploiement ne puisse pas sélectionner la mauvaise.

Comment mettre en œuvre l’authentification par certificat ?

L’authentification par certificat suit un échange asynchrone de type défi-réponse. Le client signe le XML localement, l’envoie, interroge l’état de l’opération, puis échange exactement une fois un jeton temporaire.

1. Demander un défi

Appelez POST /auth/challenge. Conservez à la fois la valeur du défi et son horodatage. Valable dix minutes, le défi associe la requête suivante à une nouvelle tentative d’authentification et empêche la réutilisation d’un ancien document signé. Créez-en un nouveau à chaque tentative au lieu de le mettre en cache.

2. Construire AuthTokenRequest

Construisez la requête XML avec :

• le défi ;
• le type et la valeur de l’identifiant de contexte ;
• le type d’identifiant du sujet ;
• une AuthorizationPolicy facultative qui restreint les adresses IPv4, plages ou masques autorisés.

Si le certificat contient le NIP de l’entreprise, le sujet peut s’authentifier directement. Si une personne signe pour une entreprise, KSeF extrait son identifiant du certificat et vérifie ses autorisations dans le contexte de l’entreprise. Pour les certificats qualifiés dépourvus de NIP ou de PESEL, l’empreinte d’un certificat autorisé peut être nécessaire.

3. Créer une signature XAdES conforme

Signez le XML avec le certificat d’identité choisi et sa clé privée. Ne partez pas du principe qu’un ancien exemple XAdES pour KSeF 1.0 est toujours accepté. L’API 2.1.0 a renforcé la validation XAdES et, d’après le journal des modifications de l’API KSeF, les règles actuelles s’appliquent déjà à tous les environnements actifs. Les exigences XAdES actuelles acceptent les signatures enveloppées et enveloppantes, mais rejettent les signatures détachées ; elles fixent également les tailles minimales des clés RSA et EC.

Le ministère maintient des clients de référence en C# et en Java. Même si votre application utilise un autre langage, leurs tests constituent des exemples exécutables utiles pour la sérialisation XML, les identifiants de certificat et la construction des signatures.

4. Envoyer puis interroger l’état

Envoyez le XML signé à POST /auth/xades-signature. Une soumission réussie renvoie :

• referenceNumber, qui identifie l’opération asynchrone ;
• authenticationToken, un JWT temporaire réservé à cette opération.

Interrogez GET /auth/{referenceNumber} avec le jeton temporaire. Limitez la fréquence de ces requêtes et classez les réponses en trois catégories : traitement en cours, réussite définitive et échec définitif. Une signature non valide, un problème de certificat, une autorisation manquante ou un blocage de sécurité ne sont pas des erreurs réseau passagères. Réessayer indéfiniment avec le même document erroné ne fait que masquer la véritable panne.

5. Échanger le jeton une seule fois

Une fois l’authentification réussie, appelez POST /auth/token/redeem avec le jeton temporaire. KSeF renvoie accessToken et refreshToken. Cet échange est à usage unique : la documentation sur l’authentification indique que la réutilisation du même authenticationToken produit une réponse HTTP 400.

Voici le processus d’implémentation sous une forme compacte :

challenge = POST /auth/challenge
request = build_auth_xml(challenge, context, subject, allowed_ips)
signed_xml = xades_sign(request, identity_certificate, private_key)

operation = POST /auth/xades-signature(signed_xml)
status = poll GET /auth/{operation.referenceNumber}
  Authorization: Bearer {operation.authenticationToken}

tokens = POST /auth/token/redeem
  Authorization: Bearer {operation.authenticationToken}

call protected endpoints with tokens.accessToken
refresh before accessToken.exp with tokens.refreshToken

6. Ouvrir les sessions de facturation séparément

L’authentification n’ouvre pas de session de facturation. Lorsque vous disposez d’un jeton d’accès valide, utilisez-le pour ouvrir POST /sessions/online ou POST /sessions/batch. KSeF 2.0 sépare délibérément ces deux aspects : une seule session d’authentification peut donc autoriser davantage que l’unique ouverture de session qui caractérisait les anciennes intégrations.

Et si vous utilisez encore un jeton KSeF pour vous authentifier ?

L’ancienne branche commence par le même appel à POST /auth/challenge, mais elle ne signe pas de XML. Construisez {tokenKSeF}|{timestampMs} à partir du secret et de l’horodatage du défi, chiffrez cette valeur avec la clé publique KSeF actuelle au moyen de RSA-OAEP avec SHA-256/MGF1, puis envoyez le résultat en Base64 à POST /auth/ksef-token avec le défi, le contexte et le publicKeyId sélectionné.

Récupérez les clés de chiffrement depuis GET /security/public-key-certificates ; n’inscrivez pas une clé publique en dur dans le code. Le guide officiel de rotation des clés décrit les rotations planifiées et d’urgence. Si KSeF rejette l’identifiant d’une clé retirée ou inconnue, actualisez le jeu de clés et recommencez l’opération avec un nouveau défi.

À partir de là, l’interrogation de l’état et l’échange unique suivent le même processus que pour XAdES. Le jeton KSeF lui-même ne doit jamais apparaître dans les journaux. Il constitue le secret racine de cette branche, et ne doit être confondu ni avec l’authenticationToken temporaire, ni avec le JWT d’accès renvoyé.

Comment gérer les jetons d’accès et de renouvellement ?

Traitez les deux JWT renvoyés comme des identifiants sensibles, et non comme d’inoffensives métadonnées de session. Le jeton d’accès a une courte durée de vie, mais il reste utilisable jusqu’à l’heure exp même si un administrateur modifie entre-temps les autorisations du sujet. Un jeton d’accès nouvellement renouvelé reçoit les rôles et autorisations en vigueur.

Intégrez les contrôles suivants au client :

1. Lisez exp au lieu de coder en dur une durée supposée. Renouvelez le jeton avec une marge de sécurité et un délai aléatoire afin que toutes les instances ne le fassent pas à la même seconde.
2. N’autorisez qu’un seul renouvellement à la fois par jeu d’identifiants. Lorsque plusieurs instances détectent l’expiration, laissez-en une renouveler le jeton et partager le résultat. Les vagues de renouvellements parallèles multiplient les causes d’échec sans améliorer la disponibilité.
3. Ne journalisez jamais les jetons au porteur. Masquez les en-têtes Authorization, le corps des réponses des points de terminaison de jetons, les données des exceptions et les attributs de traçage.
4. Ne stockez pas les jetons de renouvellement dans le navigateur. Une intégration côté serveur doit les conserver dans un coffre chiffré, accessible uniquement au processus qui en a besoin.
5. En cas d’échec du renouvellement, relancez l’authentification. Si le jeton de renouvellement est expiré ou non valide, le client doit revenir au processus par certificat et non entrer dans une boucle de renouvellement sans fin.
6. Utilisez l’heure du serveur avec précaution. Un décalage d’horloge à proximité de exp provoque des erreurs d’autorisation intermittentes : surveillez donc la synchronisation de l’heure et renouvelez le jeton suffisamment tôt.

Le guide officiel indique que le jeton d’accès est valable quelques minutes et que le jeton de renouvellement peut l’être jusqu’à sept jours. Ce sont des bornes d’implémentation, pas une raison de recopier une constante numérique depuis un article de blog. Le JWT et le contrat d’API en vigueur constituent la source de vérité.

Comment les autorisations interagissent-elles avec les certificats KSeF ?

Un certificat KSeF est un justificatif d’identité, pas une clé maîtresse. La documentation sur les certificats précise que le certificat n’est associé à aucun contexte et ne contient aucune autorisation KSeF. KSeF évalue côté serveur les autorisations du sujet dans le contexte demandé.

Il en découle un modèle d’accès plus clair :

• délivrez un certificat d’identité à la personne ou à l’entité qui exploite l’intégration ;
• accordez uniquement les autorisations nécessaires dans chaque contexte fiscal ;
• interrogez les autorisations effectives pendant la configuration et le diagnostic ;
• retirez les autorisations à la fin de la relation sans révoquer inutilement le certificat d’identité dans tous les contextes ;
• révoquez le certificat si la clé privée est compromise ou si le justificatif d’identité lui-même ne doit plus être considéré comme fiable.

Pour un processus qui ne fait qu’envoyer des factures, commencez par InvoiceWrite. N’ajoutez InvoiceRead que si ce processus télécharge ou recherche réellement des factures. N’accordez pas CredentialsManage aux processus ordinaires chargés de la facturation. Le guide officiel des autorisations fournit des requêtes permettant de connaître les autorisations et les rôles actuels. Elles sont plus sûres que de déduire les droits d’une connexion réussie plusieurs mois auparavant.

Un piège mérite d’être souligné : la demande d’authentification XAdES ne comporte aucun champ requestedPermissions qui transformerait une identité largement autorisée en une session par certificat au périmètre restreint. Si une identité Owner s’authentifie, l’accès obtenu peut refléter ses droits actuels. Le principe du moindre privilège commence donc par la personne ou l’entité et par les autorisations qui lui sont accordées côté serveur, pas par le fichier du certificat. La stratégie IP facultative limite les adresses depuis lesquelles un jeton peut être utilisé, et non les opérations qu’il peut effectuer.

La révocation n’est pas instantanée pour tous les identifiants

Deux effets temporels doivent être pris en compte dans la conception :

• selon le manuel du ministère, la révocation d’un certificat KSeF de type 1 utilisé par une session active met fin à cette session ;
• le retrait d’une autorisation ne réécrit pas rétroactivement un jeton d’accès déjà délivré. Celui-ci peut rester valide jusqu’à exp ; le renouvellement récupère les autorisations actuelles.

Pour parer à une urgence, révoquez le certificat compromis et arrêtez le processus applicatif local. Pour un retrait d’accès ordinaire, supprimez les autorisations, invalidez dans votre système les données de renouvellement enregistrées et prévoyez une brève période pendant laquelle le jeton d’accès restera encore valide. Journalisez le sujet, le contexte, l’heure d’émission du jeton et le numéro de série du certificat, mais jamais la valeur du jeton ni la clé privée.

Qu’est-ce qui change entre TEST, DEMO et la production ?

Le code d’authentification doit être identique dans tous les environnements, mais pas les hypothèses de confiance.

TEST accepte les certificats autosignés. Cette commodité modifie la frontière des données : le guide officiel des environnements avertit que plusieurs intégrateurs peuvent s’authentifier dans le même contexte d’entreprise de test. Utilisez des NIP aléatoires et des données de facturation synthétiques. N’envoyez jamais dans TEST l’identité, l’adresse ou la facture d’un véritable client, ni un identifiant de production.

Ne transférez pas vers DEMO ou la production un certificat autosigné réservé à TEST. Validez dans DEMO le parcours réel du certificat, notamment la chaîne de certification, les données CSR, le chargement des secrets, les alertes d’expiration et une rotation au cours de laquelle les anciens et les nouveaux identifiants se chevauchent.

Que faut-il migrer avant l’échéance actuellement fixée à 2027 ?

Si votre intégration démarre encore avec un jeton KSeF, terminez la mise en œuvre de l’authentification par certificat avant la fin de 2026, conformément aux règles actuellement en vigueur. Une prolongation proposée pourrait modifier cette date, mais elle ne doit pas influer sur l’architecture d’une nouvelle intégration. La séquence la plus sûre est avant tout opérationnelle, et pas seulement cryptographique.

1. Inventoriez chaque jeton KSeF, son propriétaire, son contexte, ses autorisations, sa dernière utilisation et le service qui le consomme.
2. Délivrez des certificats KSeF de type 1 aux personnes ou entités concernées.
3. Mettez en œuvre dans TEST le défi XAdES, l’interrogation de l’état, l’échange du jeton et son renouvellement.
4. Exécutez le parcours par certificat dans DEMO avec un stockage des clés et une stratégie réseau proches de la production.
5. Activez l’authentification par certificat en production dans le cadre d’un déploiement progressif et maîtrisé.
6. Comparez les contextes qui fonctionnent et les autorisations effectives entre l’ancien et le nouveau parcours.
7. Basculez tout le trafic, observez au moins un cycle complet de rotation et de reprise après incident, puis révoquez les anciens jetons KSeF.

N’attendez pas décembre pour découvrir que le processus dépend d’un sceau qualifié détenu par une seule personne, que les données d’identité du CSR ne correspondent pas ou que votre HSM ne sait pas produire la signature XAdES requise. L’inscription des certificats est asynchrone, les certificats expirent et la résolution des questions de responsabilité opérationnelle prend plus de temps que le code d’un point d’accès.

L’approche de Kit pour l’authentification KSeF

L’intégration KSeF for Stripe de Kit convertit les factures Stripe finalisées au format FA(3), les transmet à KSeF et conserve les preuves obtenues dans le flux de travail de facturation. Cette expérience confirme l’architecture décrite dans ce guide : les justificatifs d’identité, le contexte fiscal, les autorisations, l’accès de courte durée à l’API, les sessions de facturation et la récupération des UPO constituent des états distincts, qui doivent le rester dans le code.

La règle pratique est simple. Utilisez les certificats pour l’identité, les autorisations pour l’habilitation, les JWT pour un accès limité dans le temps à l’API et des traces explicites pour chaque opération asynchrone. Suivez l’approche globale de Kit en matière de sécurité, surveillez le journal des modifications de KSeF, testez la rotation avant l’expiration et traitez l’échéance actuelle de 2027 comme un jalon de migration plutôt que comme un incident au Nouvel An.