KSeF-2.0-Authentifizierung für Entwickler: Leitfaden 2026

Die KSeF-2.0-Authentifizierung besteht aus zwei Ebenen: Zunächst weisen Sie eine Identität mit einer XAdES-Signatur oder einem bisherigen KSeF-Token nach. Anschließend verwenden Sie das zurückgegebene JWT-Access-Token für geschützte API-Aufrufe. Nach den am 28. August 2026 geltenden Vorschriften endet die Token-Methode am 31. Dezember 2026. Neue Produktionsintegrationen sollten KSeF-Zertifikate vom Typ 1 verwenden.

Dieser Leitfaden wurde am 28. August 2026 anhand der Dokumentation des polnischen Finanzministeriums und des offiziellen KSeF-API-Repositorys geprüft. Die API entwickelt sich weiterhin. Behandeln Sie daher das offizielle Änderungsprotokoll wie eine Abhängigkeit Ihrer Produktionsumgebung.

Wie funktioniert die KSeF-2.0-Authentifizierung?

KSeF 2.0 trennt die Authentifizierung von Rechnungssitzungen. Zunächst legen Sie fest, wer den Aufruf tätigt und in welchem Steuerpflichtigenkontext dies geschieht. Erst nach Erhalt eines accessToken können Sie eine Online- oder Batch-Sitzung öffnen, Rechnungen übermitteln, Metadaten abfragen oder UPO-Dokumente abrufen.

Dieser Ablauf kennt vier Arten von Zugangsdaten. Werden sie verwechselt, entstehen die meisten Implementierungsfehler:

Der offizielle Authentifizierungsleitfaden beschreibt das letzte Paar als JWTs, die nach einem erfolgreichen asynchronen Vorgang ausgestellt werden. Das Access-Token wird als Authorization: Bearer ... übermittelt. Es ist nicht dasselbe Objekt wie das ältere, langlebige KSeF-Token.

Kontext und Identität sind voneinander getrennt

Jede Anmeldung verbindet zwei Angaben:

1. In welchem Kontext arbeitet diese Sitzung? In der Regel ist dies ein Unternehmen, das anhand seiner NIP identifiziert wird. KSeF unterstützt jedoch auch andere Kontextkennungen.
2. Wessen Identität wird authentifiziert? Dies kann das Unternehmen sein, eine über PESEL oder NIP identifizierte Person oder eine Identität, die an den Fingerabdruck eines Zertifikats gebunden ist.

KSeF prüft, ob das authentifizierende Subjekt im ausgewählten Kontext über mindestens eine aktive Berechtigung verfügt. Der Besitz eines gültigen Zertifikats allein genügt nicht. Diese Trennung ist wichtig, wenn ein Buchhaltungsdienstleister oder ein Mitarbeiter für mehrere Unternehmen arbeitet: Ein Identitätszertifikat kann in mehreren Kontexten verwendbar sein, während die Berechtigungen je Kontext unterschiedlich ausfallen.

Welche KSeF-Authentifizierungsmethode sollten Sie 2026 wählen?

Verwenden Sie für eine neue Produktionsintegration XAdES mit einem KSeF-Authentifizierungszertifikat vom Typ 1. Unterstützen Sie bisherige KSeF-Tokens nur noch vorübergehend für die Migration. Die derzeit geltende Verordnung erlaubt diese Methode bis zum 31. Dezember 2026. Nach aktuellen Angaben des Ministeriums bleiben ab dem 1. Januar 2027 Zertifikate als Authentifizierungsmethode bestehen.

Bei der Frist ist eine Einschränkung zu beachten. Im Juni 2026 schlug das Ministerium eine Verlängerung für KSeF-Tokens vor, verbunden mit kürzeren Gültigkeitsfristen und Vorgaben zur Erneuerung. Zum Prüfdatum dieses Artikels handelt es sich dabei um einen Konsultationsvorschlag, nicht um geltendes Recht. Planen Sie bis zu einer Änderung der Verordnung mit der verbindlichen Frist.

Die Unterscheidung ergibt sich unmittelbar aus dem KSeF-2.0-Handbuch des polnischen Finanzministeriums: Ein Zertifikat weist die Identität nach, enthält aber keine KSeF-Berechtigungen. Ein KSeF-Token enthält dagegen einen Teil der Berechtigungen und ist auf einen einzigen Kontext beschränkt.

Verwenden Sie kein Offline-Zertifikat zur Authentifizierung

KSeF stellt zwei Zertifikatstypen für unterschiedliche Zwecke aus:

• Authentication signiert die Anmeldeanfrage.
• Offline weist in einem Offline-Ablauf die Echtheit des Ausstellers und die Unversehrtheit der Rechnung nach.

Ein Offline-Zertifikat kann keine API-Aufrufe authentifizieren. Der offizielle Zertifikatsleitfaden warnt außerdem davor, Nachweise für Offline-Rechnungen mit einem Authentifizierungszertifikat zu signieren. Speichern und kennzeichnen Sie die beiden privaten Schlüssel getrennt, damit ein Deployment nicht den falschen Schlüssel auswählt.

Wie implementieren Sie die Zertifikatsauthentifizierung?

Die Zertifikatsauthentifizierung ist ein asynchroner Challenge-Response-Ablauf. Ihr Client signiert XML lokal, übermittelt es, fragt den Status des Vorgangs ab und löst ein temporäres Token genau einmal ein.

1. Challenge anfordern

Rufen Sie POST /auth/challenge auf. Bewahren Sie sowohl den Challenge-Wert als auch dessen Zeitstempel auf. Die Challenge ist zehn Minuten gültig. Sie bindet die nächste Anfrage an einen neuen Authentifizierungsversuch und verhindert, dass ein altes signiertes Dokument erneut verwendet wird. Erstellen Sie für jeden Versuch eine neue Challenge, anstatt sie zwischenzuspeichern.

2. AuthTokenRequest erstellen

Erstellen Sie die XML-Anfrage mit folgenden Angaben:

• der Challenge,
• Typ und Wert der Kontextkennung,
• Typ der Subjektkennung,
• einer optionalen AuthorizationPolicy, die zulässige IPv4-Adressen, Adressbereiche oder Masken einschränkt.

Enthält das Zertifikat die NIP des Unternehmens, kann sich das Subjekt direkt authentifizieren. Signiert eine Person für ein Unternehmen, ermittelt KSeF die Kennung der Person aus dem Zertifikat und prüft ihre Berechtigungen im Kontext des Unternehmens. Bei qualifizierten Zertifikaten ohne NIP oder PESEL kann ein autorisierter Zertifikatsfingerabdruck erforderlich sein.

3. Eine konforme XAdES-Signatur erstellen

Signieren Sie das XML mit dem ausgewählten Identitätszertifikat und dessen privatem Schlüssel. Gehen Sie nicht davon aus, dass ein altes XAdES-Beispiel aus KSeF 1.0 weiterhin akzeptiert wird. API 2.1.0 hat die XAdES-Validierung verschärft. Laut dem Änderungsprotokoll der KSeF-API gelten die aktuellen Regeln bereits in allen Live-Umgebungen. Die aktuellen XAdES-Anforderungen akzeptieren enveloped und enveloping signatures, weisen detached signatures jedoch zurück. Außerdem legen sie Mindestgrößen für RSA- und EC-Schlüssel fest.

Das Ministerium unterhält Referenz-Clients für C# und Java. Auch wenn Ihre Anwendung eine andere Sprache verwendet, bieten deren Tests ausführbare Beispiele für die XML-Serialisierung, Zertifikatskennungen und die Erstellung von Signaturen.

4. Übermitteln und Status abfragen

Senden Sie das signierte XML an POST /auth/xades-signature. Eine erfolgreiche Übermittlung gibt Folgendes zurück:

• referenceNumber zur Identifizierung des asynchronen Vorgangs;
• authenticationToken, ein temporäres JWT, das ausschließlich für diesen Vorgang verwendet wird.

Fragen Sie GET /auth/{referenceNumber} mit dem temporären Token ab. Begrenzen Sie die Abfragefrequenz und unterscheiden Sie drei Zustände: noch in Verarbeitung, endgültig erfolgreich und endgültig fehlgeschlagen. Ungültige Signaturen, Zertifikatsprobleme, fehlende Berechtigungen und Sicherheitsblockierungen sind keine vorübergehenden Netzwerkfehler. Wenn Sie dasselbe fehlerhafte Dokument unbegrenzt erneut senden, verschleiern Sie lediglich den eigentlichen Fehler.

5. Einmalig einlösen

Rufen Sie nach erfolgreicher Authentifizierung POST /auth/token/redeem mit dem temporären Token auf. KSeF gibt accessToken und refreshToken zurück. Das Einlösen ist nur einmal möglich. Laut Authentifizierungsdokumentation führt die erneute Verwendung desselben authenticationToken zu HTTP 400.

Ein kompakter Implementierungsentwurf sieht so aus:

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. Rechnungssitzungen getrennt öffnen

Mit der Authentifizierung wird keine Rechnungssitzung geöffnet. Sobald Sie ein gültiges Access-Token besitzen, öffnen Sie damit POST /sessions/online oder POST /sessions/batch. KSeF 2.0 trennt diese Aufgaben bewusst. Eine Authentifizierungssitzung kann daher mehr als nur den einzelnen Vorgang zum Öffnen einer Sitzung autorisieren, auf den ältere Integrationen ausgelegt waren.

Was ist zu tun, wenn Sie noch ein KSeF-Token zur Authentifizierung verwenden?

Der bisherige Zweig beginnt ebenfalls mit POST /auth/challenge, signiert jedoch kein XML. Bilden Sie {tokenKSeF}|{timestampMs} aus dem Geheimnis und dem Challenge-Zeitstempel, verschlüsseln Sie den Wert mit dem aktuellen öffentlichen KSeF-Schlüssel über RSA-OAEP mit SHA-256/MGF1 und senden Sie das Base64-Ergebnis zusammen mit Challenge, Kontext und ausgewählter publicKeyId an POST /auth/ksef-token.

Rufen Sie die Verschlüsselungsschlüssel über GET /security/public-key-certificates ab. Hinterlegen Sie keinen einzelnen öffentlichen Schlüssel fest im Code. Der offizielle Leitfaden zur Schlüsselrotation beschreibt geplante Rotationen und Notfallrotationen. Weist KSeF eine zurückgezogene oder unbekannte Schlüsselkennung zurück, laden Sie den Schlüsselsatz neu und wiederholen Sie den Vorgang mit einer neuen Challenge.

Ab diesem Punkt entsprechen die Statusabfrage und das einmalige Einlösen dem XAdES-Ablauf. Das KSeF-Token selbst darf niemals in Protokollen erscheinen. Es ist das Stammgeheimnis dieses Zweigs, nicht das temporäre authenticationToken oder das zurückgegebene Access-JWT.

Wie sollten Access- und Refresh-Tokens behandelt werden?

Behandeln Sie beide zurückgegebenen JWTs als Anmeldedaten, nicht als harmlose Sitzungsmetadaten. Das Access-Token ist kurzlebig, kann aber bis zum Zeitpunkt exp weiterverwendet werden, selbst wenn ein Administrator währenddessen die Berechtigungen des Subjekts ändert. Ein neu ausgestelltes Access-Token enthält die zu diesem Zeitpunkt geltenden Rollen und Berechtigungen.

Bauen Sie folgende Schutzmaßnahmen in den Client ein:

1. Lesen Sie exp aus und codieren Sie keine angenommene Gültigkeitsdauer fest. Erneuern Sie das Token mit einem Sicherheitspuffer und einem zufälligen Versatz, damit nicht alle Worker in derselben Sekunde eine Erneuerung anstoßen.
2. Lassen Sie pro Satz von Zugangsdaten nur eine Erneuerung gleichzeitig zu. Wenn mehrere Worker das nahende Ablaufdatum erkennen, lassen Sie einen von ihnen das Token erneuern und das Ergebnis mit den anderen teilen. Parallele Erneuerungswellen schaffen zusätzliche Fehlerquellen, ohne die Verfügbarkeit zu erhöhen.
3. Protokollieren Sie niemals Bearer-Tokens. Maskieren Sie Authorization-Header, Antworttexte der Token-Endpunkte, Exception-Payloads und Tracing-Attribute.
4. Speichern Sie Refresh-Tokens nicht im Browser. Eine serverseitige Integration sollte sie in einem verschlüsselten Speicher für Zugangsdaten ablegen. Erlauben Sie den Zugriff nur dem Worker, der sie benötigt.
5. Authentifizieren Sie sich nach einer fehlgeschlagenen Erneuerung erneut. Bei einem abgelaufenen oder ungültigen Refresh-Token sollte der Client zum Zertifikatsablauf zurückkehren, nicht in eine unbegrenzte Erneuerungsschleife geraten.
6. Berücksichtigen Sie die Serverzeit sorgfältig. Zeitabweichungen in der Nähe von exp verursachen sporadische Autorisierungsfehler. Überwachen Sie daher die Zeitsynchronisierung und erneuern Sie das Token frühzeitig.

Der offizielle Leitfaden beschreibt eine Gültigkeit des Access-Tokens von mehreren Minuten und eine Gültigkeit des Refresh-Tokens von bis zu sieben Tagen. Dies sind Grenzen der Implementierung, kein Grund, eine Zahlenkonstante aus einem Blogartikel zu übernehmen. Maßgeblich sind das JWT und der aktuelle API-Vertrag.

Wie hängen Berechtigungen und KSeF-Zertifikate zusammen?

Ein KSeF-Zertifikat ist ein Identitätsnachweis, kein Generalschlüssel. Laut Zertifikatsdokumentation ist das Zertifikat keinem Kontext zugeordnet und enthält keine KSeF-Berechtigungen. KSeF prüft die Berechtigungen des Subjekts für den angeforderten Kontext auf dem Server.

Daraus ergibt sich ein übersichtlicheres Zugriffsmodell:

• Stellen Sie der Person oder Organisation, welche die Integration betreibt, ein Identitätszertifikat aus.
• Erteilen Sie in jedem Steuerpflichtigenkontext nur die erforderlichen Berechtigungen.
• Fragen Sie die wirksamen Berechtigungen bei der Einrichtung und Fehlerdiagnose ab.
• Entziehen Sie Berechtigungen, wenn die Geschäftsbeziehung endet, ohne das Identitätszertifikat unnötigerweise überall zu widerrufen.
• Widerrufen Sie das Zertifikat, wenn der private Schlüssel kompromittiert wurde oder dem Identitätsnachweis selbst nicht mehr vertraut werden soll.

Beginnen Sie bei einem Worker, der ausschließlich Rechnungen übermittelt, mit InvoiceWrite. Fügen Sie InvoiceRead nur hinzu, wenn dieser Prozess tatsächlich Rechnungen herunterlädt oder durchsucht. Reguläre Rechnungs-Worker sollten keinen Zugriff auf CredentialsManage erhalten. Der offizielle Berechtigungsleitfaden stellt Abfragen für aktuelle Berechtigungen und Rollen bereit. Diese sind zuverlässiger, als den heutigen Zugriff aus einer Monate zurückliegenden erfolgreichen Anmeldung abzuleiten.

Eine Falle verdient besondere Beachtung: Die XAdES-Authentifizierungsanfrage besitzt kein Feld requestedPermissions, das den Zugriff einer Identität mit umfassenden Berechtigungen für die Zertifikatssitzung einschränkt. Authentifiziert sich eine Identität mit Owner-Rechten, kann der daraus resultierende Zugriff deren aktuelle Rechte widerspiegeln. Das Prinzip der minimalen Rechte beginnt daher bei der Person oder Organisation und deren serverseitig erteilten Berechtigungen, nicht bei der Zertifikatsdatei. Die optionale IP-Richtlinie begrenzt, von wo aus ein Token verwendet werden darf, nicht welche Vorgänge es ausführen kann.

Der Widerruf wirkt nicht bei allen Anmeldedaten sofort

Für den Betrieb zählen zwei zeitliche Effekte:

• Laut dem Handbuch des Ministeriums beendet der Widerruf eines in einer aktiven Sitzung verwendeten KSeF-Zertifikats vom Typ 1 diese Sitzung.
• Wird eine Berechtigung entzogen, wird ein bereits ausgestelltes Access-Token nicht rückwirkend geändert. Das Token kann bis exp gültig bleiben; bei einer Erneuerung werden die aktuellen Berechtigungen übernommen.

Widerrufen Sie zur dringenden Schadensbegrenzung das kompromittierte Zertifikat und halten Sie den lokalen Worker an. Bei einer regulären Beendigung der Zusammenarbeit entziehen Sie die Berechtigungen, markieren gespeicherte Refresh-Zugangsdaten in Ihrem System als ungültig und rechnen mit einer kurzen Restlaufzeit des Access-Tokens. Protokollieren Sie Subjekt, Kontext, Ausstellungszeitpunkt des Tokens und Seriennummer des Zertifikats, jedoch niemals den Tokenwert oder den privaten Schlüssel.

Was ändert sich zwischen TEST, DEMO und Produktion?

Der Authentifizierungscode sollte in allen Umgebungen identisch sein, nicht jedoch die Vertrauensannahmen.

TEST akzeptiert selbstsignierte Zertifikate. Dadurch entsteht ein besonderes Risiko für Testdaten: Der offizielle Leitfaden zu den Umgebungen warnt davor, dass sich mehrere Integratoren im selben Test-Unternehmenskontext authentifizieren können. Verwenden Sie zufällige NIPs und synthetische Rechnungsdaten. Übermitteln Sie niemals die reale Identität, Adresse oder Rechnung eines Kunden oder Zugangsdaten der Produktionsumgebung an TEST.

Übernehmen Sie ein selbstsigniertes Zertifikat, das ausschließlich für TEST vorgesehen ist, nicht in DEMO oder die Produktion. Prüfen Sie den echten Zertifikatspfad in DEMO vollständig: Validierung der Zertifikatskette, CSR-Daten, Laden von Geheimnissen, Ablaufwarnungen für Zertifikate sowie eine Rotation mit überlappender Gültigkeit der alten und neuen Zugangsdaten.

Was sollten Sie vor der derzeitigen Frist 2027 migrieren?

Beginnt Ihre Integration noch mit einem KSeF-Token, schließen Sie die Zertifikatsauthentifizierung nach den derzeit geltenden Vorschriften vor Ende 2026 ab. Eine vorgeschlagene Verlängerung könnte das Datum ändern, sollte aber nichts an der Architektur einer neuen Integration ändern. Die sicherste Reihenfolge orientiert sich am Betrieb, nicht nur an der Kryptografie.

1. Erfassen Sie jedes KSeF-Token sowie dessen Inhaber, Kontext, Berechtigungen, letzte Verwendung und den Dienst, der es nutzt.
2. Stellen Sie den zuständigen Personen oder Organisationen KSeF-Zertifikate vom Typ 1 aus.
3. Implementieren Sie in TEST den XAdES-Ablauf mit Challenge, Statusabfrage, Einlösung und Erneuerung.
4. Testen Sie den Zertifikatsweg in DEMO mit produktionsnaher Schlüsselspeicherung und Netzwerkrichtlinie.
5. Aktivieren Sie die Zertifikatsauthentifizierung in der Produktion schrittweise und kontrolliert.
6. Gleichen Sie erfolgreiche Kontexte und wirksame Berechtigungen zwischen altem und neuem Weg ab.
7. Stellen Sie den gesamten Datenverkehr um, beobachten Sie mindestens einen vollständigen Rotations- und Fehlerbehebungszyklus und widerrufen Sie anschließend die alten KSeF-Tokens.

Warten Sie nicht bis Dezember, um festzustellen, dass der Prozess von einem qualifizierten Siegel abhängt, über das nur eine Person verfügt, dass die CSR-Identitätsdaten nicht übereinstimmen oder dass Ihr HSM die erforderliche XAdES-Signatur nicht erzeugen kann. Die Ausstellung von Zertifikaten erfolgt asynchron, Zertifikate laufen ab, und betriebliche Zuständigkeiten zu klären dauert länger, als den Code für die Endpunkte zu schreiben.

So setzt Kit die KSeF-Authentifizierung um

Die Integration KSeF for Stripe von Kit wandelt fertiggestellte Stripe-Rechnungen in FA(3) um, übermittelt sie an KSeF und bewahrt die daraus entstehenden Nachweise im Abrechnungsablauf auf. Diese Erfahrung bestätigt die in diesem Leitfaden beschriebene Architektur: Identitätsnachweise, Steuerpflichtigenkontext, Berechtigungen, kurzlebiger API-Zugriff, Rechnungssitzungen und UPO-Abruf sind getrennte Zustände und sollten auch im Code getrennt bleiben.

Der praktische Maßstab ist einfach: Verwenden Sie Zertifikate für die Identität, Berechtigungen für die Autorisierung, JWTs für zeitlich begrenzten API-Zugriff und nachvollziehbare Zustandsdaten für jeden asynchronen Vorgang. Beachten Sie Kits umfassenderen Sicherheitsansatz, verfolgen Sie das KSeF-Änderungsprotokoll, testen Sie die Rotation vor Ablauf des Zertifikats und behandeln Sie die derzeitige Token-Frist 2027 als Meilenstein Ihrer Migration – nicht als Zwischenfall zum Jahreswechsel.