KSeF 2.0 explained: authentication, sessions, UPO, offline modes, QR codes

KSeF 2.0 is the version of Poland's national e-invoice system that has been the only one in force since 1 February 2026, when KSeF 1.0 was switched off. Software authenticates with a qualified signature or a KSeF token and receives JWT access tokens, opens an interactive or batch session, sends AES-encrypted FA(3) XML, and gets back a 35-character KSeF number per invoice and an official acknowledgement (UPO) per session. Offline modes, QR codes and KSeF certificates cover the cases where the invoice reaches the buyer outside the system.

What changed from KSeF 1.0 to 2.0

KSeF 2.0 is a new API contract, not a patch: authentication was separated from sessions, JWT tokens replaced the old session-bound login, encryption became mandatory in every mode, names were made RESTful, and a certificate module was added.

The Ministry's own overview for integrators lists the key changes: authentication as an independent step producing reusable, refreshable and revocable tokens; one initialisation model for both POST /sessions/online and POST /sessions/batch, each taking a form code and an encrypted AES key; mandatory client-side encryption of every invoice with RSA-OAEP (SHA-256, MGF1-SHA-256) protecting the session key; consistent identifiers (NIP, PESEL, fingerprint) as explicit enums; and internal KSeF certificates for authentication and offline issuance. The API is described in OpenAPI 3.0.4 with interactive documentation at api.ksef.mf.gov.pl/docs/v2, and the Ministry publishes open-source client libraries for C# and Java.

Environments: test, demo, production

Three public environments exist, and only production has legal effect.

The Ministry's timeline: open API tests began 30 September 2025, the demo API opened 15 October 2025, the KSeF 1.0 test environment was closed on 1 September 2025, and production KSeF 2.0 went live on 1 February 2026 after a technical break from 26 to 31 January. URLs returned by the API always point to the environment that was called. Scheduled maintenance on the test environments may run 16:00–18:00, and only integration-relevant changes are announced in the changelog.

Authentication: signature, KSeF token, certificates

Every protected call needs a JWT accessToken. To obtain one, the client proves who it is (the authenticating subject) and for whom it acts (the context, usually a NIP), and KSeF checks that the subject holds at least one active permission in that context.

1. Challenge. POST /auth/challenge returns a challenge valid for 10 minutes.
2. Proof of identity, one of two ways:
   • XAdES signature. The client builds an AuthTokenRequest XML (challenge, context identifier — NIP, internal ID or NIP-VAT-EU composite — and subject identifier type certificateSubject or certificateFingerprint, optionally an allowed-IP policy) and signs it. Accepted signers: a qualified certificate of a natural person carrying PESEL or NIP, a qualified organisation seal carrying the NIP, a Trusted Profile signature, a KSeF certificate, or a Peppol service-provider certificate. Self-signed certificates are accepted only on TEST.
   • KSeF token. A JSON request with a previously generated system token. Tokens are generated with POST /tokens after at least one XAdES authentication, carry a permission list such as InvoiceRead, InvoiceWrite, CredentialsRead, CredentialsManage, and are confidential secrets.
3. Tokens. The response yields an accessToken and a refreshToken; access tokens expire, can be refreshed without re-authenticating, and are revoked automatically when the permissions are lost. Sessions are listed under GET /auth/sessions and revoked with DELETE /auth/sessions/current or by reference number.

KSeF certificates are issued by the system itself and are not qualified certificates. A certificate carries exactly one type: Authentication (key usage digital signature) for logging in, or Offline (key usage non-repudiation) for signing the second QR code on offline invoices; it cannot do both. Enrolment (/certificates/enrollments) is possible only after an XAdES authentication, in the subject's own name, with a PKCS#10 CSR, and a certificate is valid for at most two years. Default limits: 300 applications and 100 active certificates per NIP, 12 and 6 per PESEL or fingerprint.

Permissions themselves are granted in the system: a company that has no qualified seal designates a natural person on form ZAW-FA, and that person then grants further rights, for example to an accountant or to a software integrator's certificate.

Sessions: interactive and batch

An interactive session sends invoices one by one and suits invoicing software; a batch session sends a ZIP of up to 10,000 invoices in encrypted parts of at most 100 MB and suits bulk uploads. Both start with the same JSON: the form code (schema version) and the session's AES key encrypted with the Ministry's public key.

Interactive

1. Generate a 256-bit AES key and 128-bit IV; encrypt the key with RSA-OAEP using the current public key from GET /security/public-key-certificates.
2. POST /sessions/online with the form code (FA(3)) and the encrypted key. The response gives a referenceNumber and validUntil; a session lives 12 hours and several may be open in parallel.
3. POST /sessions/online/{referenceNumber}/invoices with each invoice encrypted with AES-256-CBC (PKCS#7 padding), its hash and size. The response returns a document reference number.
4. Poll GET /sessions/{referenceNumber} and GET /sessions/{referenceNumber}/invoices for per-invoice status, the KSeF number and the invoice UPO.
5. POST /sessions/online/{referenceNumber}/close. Closing starts asynchronous generation of the collective UPO for the session.

Batch

The client zips the XML files, splits the ZIP binarily into parts of at most 100 MB before encryption, encrypts each part, describes the parts in fileParts when opening POST /sessions/batch, uploads them to the URLs returned, and closes the session. The Ministry recommends recording a SHA-256 hash per original XML so that KSeF statuses can be matched to local documents. Default limits per context: 1 MB per invoice (3 MB with an attachment), 10,000 invoices per session, 500 per collective identifier.

KSeF number and UPO

The KSeF number is the proof that an invoice exists; the UPO (Urzędowe Poświadczenie Odbioru) is the official acknowledgement of a session and its invoices.

The number is always 35 characters: NIP-YYYYMMDD-XXXXXXXXXXXX-CC — the seller's ten-digit NIP, the date the invoice was accepted for processing, a twelve-character hexadecimal technical part and a two-character CRC-8 checksum (polynomial 0x07, initial value 0x00). Software can validate a number offline by recomputing the checksum. It must not be confused with the seller's own invoice number in field P_2.

Before assigning a number KSeF checks two things: that the XML conforms to the current schema, and that the sender has the right to issue in that context. A rejected file is not an invoice; it is corrected and resubmitted, not "corrected" with a credit note. For an online invoice the issue date is the date of transmission, as long as field P_1 matches it, even if the number arrives the next day.

Offline modes

Four modes let issuing continue when the connection or the system is not available; three of them require the invoice to be sent to KSeF afterwards, with offlineMode: true, within a statutory deadline.

In offline modes the issue date is the date in P_1, not the transmission date. Except in emergency mode, the buyer receives the invoice in KSeF and is not handed a copy before transmission; in emergency mode the FA(3) file is delivered to the buyer in an agreed way and numbered afterwards. If an announced failure falls inside the offline24 or unavailability window, the deadline moves to 7 business days after that failure ends. An invoice issued outside KSeF must never be re-issued inside it — that creates two invoices for one sale.

QR codes on visualisations

A visualisation handed over outside KSeF — PDF, print, e-mail attachment — carries a QR code so that anyone can verify the invoice in the system; offline invoices carry two.

• KOD I links to the verification page and lets the holder check and, with additional data, download the invoice. Under it stands the KSeF number when known, or the word OFFLINE before the number is assigned.
• KOD II confirms the issuer's identity for offline invoices. It is signed with an Offline KSeF certificate; an Authentication certificate cannot be used. KSeF verifies that the certificate exists, is valid, unrevoked and unblocked, and that its subject holds active issuing rights in the context.

Codes are generated locally by the client from the invoice data (ISO/IEC 18004:2024) and the link host follows the environment. A visualisation may be handed to the buyer only once the invoice is registered in KSeF, except in emergency mode.

Receiving invoices

Buyers collect invoices from KSeF instead of receiving them by e-mail. The API offers invoice queries and incremental download of newly issued invoices in the buyer's context, and the Ministry confirms that software may fetch them automatically. Foreign buyers without a NIP cannot log in and are sent a copy with KOD I instead. The FA(3) file that comes back is documented on the FA(3) schema page.

How KRONENWERK handles this

NOT YET READY for transmission. KRONENWERK's KSeF 2.0 module — token authentication, interactive session, FA(3) submission, UPO retrieval and receiving — is built and environment-dependent, and it has not been used against the production KSeF. FA(3) generation and schema validation are SUPPORTED WITH LIMITATIONS. KRONENWERK does not sell subscriptions to Polish companies until production submission has been proven; see the Poland hub and the country page Poland.

The design follows the rule the system imposes: an invoice is not "issued" in KRONENWERK until KSeF has returned a number, and a submission whose answer was lost is reconciled by asking KSeF what it holds rather than resent, because a blind retry would create a second legal invoice. Developers integrating their own systems can compare this with KSeF integration and the step-by-step KSeF guide. This page describes the Ministry's system; it is not tax or legal advice.

Frequently asked questions

Do I need a qualified signature to use the KSeF API?

For the first authentication, yes — a qualified certificate, a qualified seal, a Trusted Profile signature or a KSeF certificate. After that, software can use a KSeF token or a KSeF Authentication certificate.

What is the difference between the KSeF number and the UPO?

The KSeF number is the 35-character identifier assigned to each accepted invoice; the UPO is the official acknowledgement generated for a session, available after the session is closed, and also per invoice.

What does offline24 mean?

The taxpayer issues an FA(3) invoice without a connection and must transmit it to KSeF by the next business day; the buyer receives it in KSeF, and the visualisation carries two QR codes.

Can I test against real data on the test environment?

No. The Ministry says TEST data is shared between integrators and must use random NIPs and anonymised data; DEMO uses real credentials but has no legal effect.

Is every invoice encrypted?

Yes. In KSeF 2.0 every invoice, interactive or batch, is encrypted client-side with an AES key that is itself encrypted with the Ministry's public key when the session opens.