KSeF in 2026: How to generate and verify authorization tokens? Technical guide

KSeF 2.0 shifts the focus from "issuing PDFs" to a controlled technical process: authentication, permissions, API sessions, acceptance statuses, and handling exceptional scenarios such as offline mode and outages. In practice, this means an integration does not end when "the system sends an invoice". It ends only when the invoice is accepted by KSeF, receives a KSeF number, and the process includes a defined path for periods when the system is unavailable.

Authorization tokens are one of the mechanisms that simplify launching an integration and automating work with KSeF. Tokens alone do not solve issues related to permissions, roles, or entity representation. If these elements are not properly configured, a token may work technically, while operations still fail due to authorization errors or lack of access to invoices.

This article walks through a practical model: what to prepare before working with tokens, how to generate them in MCU, how to test them at the API and permissions level, and how to connect this with the offline procedure so invoicing continues even when KSeF is unavailable.

Glossary

• Authentication - the method used to confirm the identity of a person or system.
• Authorization - the scope of permissions: what actions can be performed in KSeF.
• Authorization token - an integration authentication mechanism in KSeF 2.0 that does not grant permissions, but enables the use of permissions already assigned.
• MCU - Module of Certificates and Permissions, where permissions and security tools are managed in KSeF 2.0.

Why KSeF authorization tokens matter in 2026

In production environments, repeatability and automation are critical, especially when invoices are issued from an ERP, a sales system, or a billing platform. Tokens allow an integration to operate without manual authentication for each operation.

Most common token use cases:

• automated invoice submission to KSeF from a finance or sales system
• automated retrieval of purchase invoices from KSeF into document workflows and accounting
• batch processing: metadata retrieval, package exports, status synchronization

KSeF 1.0 tokens vs KSeF 2.0

In KSeF 2.0, the way permissions and integrations are managed changes, in particular through MCU. This distinction matters because organizations often try to carry over assumptions from KSeF 1.0 into KSeF 2.0, which leads to configuration and testing issues.

In this article, the process described applies to KSeF 2.0 and MCU, which is the operationally relevant model for 2026 implementations.

Prerequisites - before generating a KSeF authorization token

Before moving to tokens, align two layers:

• Authentication - who enters the system and how identity is confirmed.
• Authorization - what actions the person or system can perform in KSeF.

The authentication method depends on the legal form and how the entity is represented:

• sole proprietorships and individuals - most often Trusted Profile or qualified signature, depending on the scenario
• companies and other entities - typically a qualified electronic seal or appointing a person responsible for KSeF access according to the organization’s procedure

Next, roles and permissions must be set. Operationally, this division typically applies:

• permissions to view and download invoices
• permissions to issue invoices
• permissions to delegate and manage access

Only then should you proceed to tokens, because a token does not "add" permissions. If a role does not have the right to download or issue invoices, the integration may authenticate, but operations will still fail.

How to generate tokens in MCU for KSeF 2.0

In KSeF 2.0, tokens are generated in the Module of Certificates and Permissions (MCU). The Ministry of Finance made token generation available in MCU on December 8, 2025 and communicated it as part of the preparation for KSeF 2.0.

Step 1 - authentication and entity context

Access to MCU begins with authentication appropriate to the entity’s legal form and representation method. This is where operational mistakes most often occur: the login is correct, but actions are performed in the wrong context, for example different tax ID, different role, missing delegation, or an account without the required permissions.

In practice, before generating a token, confirm:

• you are operating in the correct entity context
• the account has the correct role for access management and integration
• delegations are configured to match how the process should operate in your organization

Step 2 - confirm permissions before generating a token

A token is not "granting permissions". A token is a method for authenticating an integration that uses permissions already granted. If roles are not clearly defined and assigned, the integration may authenticate successfully, while operations still fail due to authorization errors.

Before generating a token, confirm three areas:

• who manages permissions and delegations in the organization
• who has permissions to issue invoices
• who has permissions to access invoices, meaning view and download

This shortens later diagnostics, because most token issues come from authorization, not from the token itself.

Step 3 - generate the token in MCU

In MCU, you generate a token for KSeF 2.0 and assign it to a use scenario, most often as a system integration token. After generation, treat the token as a production secret.

Good process practice before clicking "generate":

• name the token unambiguously: system, environment, owner
• define which operations the token is intended for, for example read-only or issuing
• agree where the token will be stored and who will have access

Step 4 - storage and access control

At the organizational standard level, use simple rules without depending on specific tools:

• store the token only in a dedicated secrets repository
• restrict access to implementation and operations roles
• separate environments: separate tokens for test, staging, and production

This matters for security, auditability, and maintenance. A token that exists in multiple places and circulates among people eventually becomes a source of incidents or process downtime.

How to verify a token in practice

Token verification should answer three questions:

• does the token work technically (authentication and session)
• does the token have the right permissions (authorization)
• does the process end with an operational outcome (statuses, UPO, KSeF number)

The best approach is a three-layer test.

Layer 1 - technical verification

Goal: confirm the integration can authenticate with the token and begin working with the API.

What to check:

• whether the token allows you to initiate a session and proceed to operations requiring an active session
• whether the integration correctly handles errors: invalid token, expired token, revoked token, missing entity context
• whether the integration controls retries and does not create loops that overload systems

At this layer, you are not testing "can we issue an invoice". You are testing whether the integration can enter an operational mode.

Layer 2 - permissions verification

Goal: confirm the token not only works, but provides real access to the operations you need.

The simplest testing method is to run an operation that requires a specific permission:

• for read access: search invoices by metadata or download a sample invoice
• for issuing: attempt to issue a test invoice

If the token works but permissions are incomplete, a typical symptom is that the session initiates successfully, but operations return an access denied error. This is not a token issue, but a roles and delegations configuration issue.

Layer 3 - process closure in KSeF

Goal: confirm the operation ends in what matters operationally.

For issuing invoices, the minimum end-to-end test should close:

• sending the invoice to KSeF
• receiving the UPO
• receiving the KSeF number
• invoice acceptance status
  
  

Only after these conditions are met can the issuing process be considered stable and the integration considered end-to-end.

Most common issues in token testing

Below are the most common scenarios that create an integration that "seems to work".

The token works, but operations are blocked

Symptom: the integration authenticates, but invoice read or issue operations return access denied.

Most common causes:

• the role lacks the required permissions scope, for example read-only while the integration tries to issue
• delegation was granted for a different user, entity, or scope than expected
• the integration runs in a different context than intended, for example environment, tax ID, role

Fastest remediation path:

• confirm the entity context in which the integration runs
• confirm the role and its scope: read, issuing, delegation
• confirm delegations according to the organization’s operating model

The counterparty cannot see the invoice

Symptom: the invoice was sent, but the buyer cannot see it in their KSeF view.

The most common cause is incorrect counterparty data in the invoice structure, especially using the wrong identification field for the tax ID. In practice, this is a data validation issue, not a "KSeF error".

Process recommendation:

• validate counterparty data before sending, including format and identifier type
• run tests on multiple counterparty variants, including domestic and foreign

Submission succeeded, but the process does not close with a KSeF number

Symptom: the integration "sends" an invoice, but there is no acceptance confirmation or KSeF number.

Most common causes:

• the integration does not poll status and does not handle asynchronous queues
• UPO is not retrieved
• issues in asynchronous mechanics or retry and timeout handling

Recommendation:

• treat statuses and UPO as part of the process, not an optional step
• store operation identifiers and outcome status in integration logs for each submission

Tokens and operational security

A token is a secret. At the organizational standard level, define how tokens are stored, shared, and rotated.

Minimum security standard:

• tokens stored only in a secrets repository
• no tokens in code repositories, documents, or messengers
• separate tokens per environment: test, staging, production
• access control and auditability of who accessed secrets
• least privilege: a token should have only the scope necessary for the integration
• a rotation and revocation plan in case of an incident

In practice, token security is part of operational continuity. Loss of control over a token or chaotic sharing usually results in invoicing downtime or urgent access remediation.

How to align tokens with offline mode and outages

A token solves authentication in online mode. It does not solve what happens when KSeF is temporarily unavailable or when an organization has no access to the system.

Regardless of the authentication mechanism, an organization should have an emergency procedure that defines:

• when the organization considers itself to be operating in offline mode
• how invoices are issued and stored in offline mode
• the deadline for submitting invoices to KSeF after services are restored
• how documents are delivered to recipients depending on recipient type

Two scenarios that must be distinguished

In practice, two cases appear:

• offline mode on the organization side or partial unavailability - invoices are submitted to KSeF no later than the next business day
• an official KSeF outage announced by the competent authority - invoices are submitted within a deadline counted from the end of the outage, according to the outage rules

These timelines must be consistent across procedures and tools because they affect risk control and process compliance.

Delivery matrix in an internal procedure

Many organizations use a simple rule:

• for B2B in Poland - hold delivery until the KSeF number is assigned
• for consumers or foreign counterparties - provide the PDF immediately, according to the offline process, without waiting for a KSeF number

This is not about a "nice process". It reduces disputes and misunderstandings on the recipient side.

QR and the limits of tokens

Offline modes often introduce QR codes on the invoice visualization. At this point, it helps to clearly separate two areas:

• tokens - authentication and integration work in online mode
• offline - a separate process path requiring consistent rules for issuing, storing, and later submitting invoices to KSeF

In practice, even correctly working tokens do not solve the full continuity problem. Offline is a separate implementation component.

Tokens vs KSeF certificates - a technical decision for 2026

In 2026, implementations will often be hybrid: tokens simplify starting an integration and automation, while the target security model relies on KSeF certificates, especially if the organization must support offline scenarios.

From an architecture perspective, separate:

• the authentication mechanism for the integration in online mode
• mechanisms required for offline scenarios, including confirming issuer identity in specific modes

If an organization operates strictly online and has stable infrastructure, tokens may be sufficient in the short term. If an organization has mobile or field sales, many locations, or a higher risk of connectivity loss, offline and certificates should be considered from the start.

FAQ - most common questions about KSeF authorization tokens

Do tokens in KSeF grant permissions?

No. Permissions follow from roles and delegations configuration. A token is an authentication mechanism.

How do you verify a token in an operationally meaningful way?

Verification should cover three layers: technical (session), permissions (operations), process (UPO, KSeF number, acceptance status).

What should we do when KSeF is unavailable?

The process should switch to offline mode according to the organization’s procedure, and invoices should be submitted to KSeF within the deadline defined by the applicable mode. In parallel, apply delivery rules depending on recipient type.

Are tokens sufficient for offline operation?

Tokens are an online authentication tool. Offline requires a separate process approach and typically moves into certificates and issuer verification requirements.
‍