E-Invoice Finder
Menu
Countries Compare software Deadlines Guides Checker Check obligation
ENFRDEPLNL
Poland · KSeF authentication cutover

KSeF token-to-certificate migration for ERP and API integrations

Migrate ERP and API integrations from KSeF tokens to Authentication certificates before 2027 with parallel tests, permission checks and rollback evidence.

Quick verdict:
  • Deadline: eliminate every machine login that still depends on the legacy credential this year.
  • Architecture: sign the XAdES request with Type 1, then continue with short-lived session credentials.
  • Gate: promote only a connector that proves expected allow/deny results and a rehearsed recovery path.
Get Poland readiness reportOfficial sources
Last checked: 3 August 2026Based on official sourcesClear summaryBusiness guidance, not legal advice
Official sources prioritized
Last-checked dates visible
Free checker, no signup required

What you need to know

Guide

1. Treat 2026 as an authentication architecture change

KSeF system tokens and certificates can both be used from 1 February 2026, but only certificates remain from 1 January 2027. This is not a conversion exercise, and there is no official post-deadline grace period. A system token contains the permissions declared when generated. A certificate proves identity; it carries neither company context nor KSeF permissions. The login identifies the context, and KSeF checks active permissions there. Use four phases: discover token use and baseline permissions; prepare enrollment, XAdES support and protected key storage; validate both paths in non-production and canary selected production traffic; then switch remaining integrations and remove token secrets after proven stability. Assign an integration owner, KSeF permissions administrator, security owner, operations owner and finance process owner. This makes the authentication change an owned business cutover rather than a credential swap.

Guide

2. Map token dependencies and baseline permissions

Inventory every token consumer: ERP connectors, middleware, invoice tools, scheduled jobs, robots, custom APIs, vault entries, CI/CD variables, desktop clients and support scripts. Record its KSeF context, environment, process, owner, version, secret location, network path and peak window without copying secret values. Include correction, download and polling jobs, which are easy to overlook. For each identity and context, capture active permissions and map them to required operations such as issue, receive, query or administer. The finance owner and KSeF administrator should approve this baseline because the certificate will not reproduce permissions from the token. Retain dated evidence: dependency register, permission results, connector versions, test accounts, owners and exceptions. Treat shared tokens, unknown owners, excessive rights, embedded secrets and vendors without a credible certificate release as risks that must be resolved before canary traffic.

Guide

3. Select Type 1, enroll correctly and protect the private key

Use a Type 1 Authentication certificate for ERP and API sessions. Type 2 Offline is issued separately to confirm issuer identity and invoice integrity in offline24, system-unavailability and emergency modes; it cannot authenticate an API session. Keep that offline-invoice workstream separate. Confirm who may request Type 1, which identity will operate it and which contexts it must access. Enrollment data can be obtained only after XAdES authentication, not after KSeF-token authentication, so test the responsible person's supported XAdES route before scheduling cutover. Record issuance evidence and certificate identifiers, never the private key. Generate or import the key into an approved vault, HSM or similarly controlled store where possible; restrict and log access, and separate production from test. Security approves custody and recovery controls, while the integration owner proves the application can sign without exporting the key to local files.

Guide

4. Implement XAdES authentication and handle session tokens correctly

Certificate login starts with POST /auth/challenge. The connector builds an AuthTokenRequest for the chosen context and challenge, signs it with XAdES using Type 1, submits it, and completes the documented exchange for temporary authentication, access and refresh tokens. Commercial software needs XAdES-BES signing support. The certificate does not replace JWT access tokens during a session; the application must handle their temporary storage, refresh, expiry and rejection. Keep the paths explicit. A KSeF system token is the legacy credential sent encrypted to POST /auth/ksef-token; access and refresh tokens are session credentials returned by authentication. The certificate has no company context, so AuthTokenRequest supplies it and KSeF verifies permissions server-side. Require sequence diagrams, signing details, retry limits, redacted logs and failure mapping. Reject software that merely imports a certificate but cannot demonstrate XAdES-BES and the full session-token lifecycle.

Guide

5. Build a test matrix and evidence pack

In non-production, test valid certificate and permitted context; valid identity without permission; wrong context; expired access token; refresh; stale challenge; malformed XAdES; unavailable key store; timeout; duplicate retry; and log redaction. Add representative issue, status, download and correction operations. Errors should reach operations with a correlation ID but no credentials. For example, SAP sends invoices through middleware for two Polish entities. Authenticate the Type 1 identity into each separately named context, prove its permissions, send low-risk test invoices, poll final status and reconcile KSeF references to SAP. Confirm an unauthorised third context is rejected. Finance validates totals and states; security reviews signing and key-use logs; operations measures latency, failure classes and retries. Preserve correlation IDs, timestamps, versions, expected and actual results, reconciliation and sign-offs—but never private keys, system tokens or live JWTs.

Guide

6. Use a controlled parallel run, canary and monitoring

A parallel capability is a recommended engineering safeguard, not an official mandated duration. Keep certificate and token paths separate behind a feature flag while token support exists. Shadow only safe authentication or permission checks where possible; never duplicate invoice submission for comparison. Route a canary by entity, connector instance or controlled window, beginning with low-risk transactions and expanding only after reconciliation passes. Monitor authentication success, challenge-to-session latency, XAdES errors, permission denials, refresh failures, invoice outcomes, polling delays, duplicate-prevention signals and reconciliation gaps by context and connector version. Set thresholds and owners before starting, and run during staffed hours outside critical closes. Before 2027, a token fallback may be temporarily retained with named approval, a time limit and full logging. It cannot be a durable recovery path and must be unavailable once token support ends.

Guide

7. Make cutover and rollback evidence-based decisions

Set production entry criteria: complete inventory, approved Type 1 key controls, active permissions in every context, passed XAdES and session tests, clean canary reconciliation, live alerts, confirmed support contacts and a current configuration backup. Apply a short internal change freeze so unrelated releases do not obscure results. Integration, KSeF administration, security, operations and finance should jointly approve go or no-go. Define measurable rollback triggers, such as repeated authentication failures, unexplained denials, unreconciled invoice states, unsafe retries or loss of key-store access. Before 2027, rollback may temporarily restore the isolated token path; first check KSeF status and never blindly resend uncertain invoices. After the deadline, recovery must repair the certificate path. Record approvers, metrics, times, affected contexts, reconciliation and fallback use. Exit only after a full business cycle and the agreed observation window pass without material errors.

Guide

8. Retire token secrets and avoid common migration mistakes

After every workload completes its observation window, disable the token flag, remove token references from manifests, vaults, runbooks and break-glass procedures, and revoke or invalidate old system tokens where supported. Scan repositories, CI/CD settings and workstations for copies, retaining only non-secret removal evidence. Application, security and operations owners should verify that no calls to the token endpoint remain. Do not assume automatic token conversion, use Type 2 Offline for API login, describe permissions as certificate contents, treat the certificate as a bearer session token, hard-code a private key or confuse /auth/ksef-token with XAdES authentication. Other failures include attempting enrollment through token authentication, leaving an unowned fallback, testing only successful login and skipping invoice reconciliation. Since KSeF may identify the operator but reject the context for missing permission, evidence must cover identity, context, server-side permissions, session lifecycle and end-to-end invoice results.

Guide

9. Choose certificate-capable software and set next actions

Ask suppliers to demonstrate challenge retrieval, AuthTokenRequest creation, XAdES-BES signing, context selection, temporary authentication exchange, access and refresh handling, permission-denial behaviour, protected-key integration and redacted monitoring against the current official API. Request supported versions, upgrade effort, test access, multi-entity handling, retries, duplicate controls, key-store compatibility and incident support. “Certificate ready” without a successful authenticated transaction is insufficient. Score products on functional proof, security architecture, observability, migration controls, release timing and support. Replace or contain a supplier whose delivery leaves no time for testing, canary expansion and fixes. Next, appoint owners, finish inventories and permission baselines, confirm enrollment, secure Type 1, upgrade the connector, execute tests and schedule a staffed canary. Manage expiry and rotation as linked operations, but keep this project focused on removing system-token reliance through a proven API cutover. This is practical information, not legal, tax or security advice.

Checklist

Name accountable owners for integration, KSeF permissions, key security, operations and finance reconciliation.

Inventory every ERP, middleware, job and secret store that uses a KSeF system token.

Capture approved permission baselines for each identity, context and required invoice operation.

Obtain a Type 1 Authentication certificate through a supported XAdES-authenticated enrollment route.

Protect the private key in approved storage with restricted, logged production access.

Verify XAdES-BES AuthTokenRequest signing and access/refresh token lifecycle handling.

Run positive, negative, permission, resilience and end-to-end invoice reconciliation tests.

Canary low-risk production traffic with thresholds, staffed monitoring and named rollback approvers.

Record go/no-go evidence, correlation IDs, reconciliation results and any temporary fallback use.

Disable the legacy path and revoke or remove old token secrets after proven cutover.

FAQ

When do KSeF system tokens stop working?

The Ministry of Finance states that KSeF tokens and KSeF certificates can both be used from 1 February 2026, but from 1 January 2027 only KSeF certificates remain. Do not base an implementation plan on an unofficial grace period after that date.

Can an existing KSeF token be converted into a certificate?

No automatic conversion should be expected. A system token carries permissions selected when it is generated, while a certificate is an identity and authentication credential. Enroll the appropriate certificate, confirm server-side permissions and implement the distinct certificate login flow.

Which KSeF certificate type should an ERP use for API authentication?

Use a Type 1 Authentication certificate. Type 2 Offline serves issuer-identity and invoice-integrity purposes in offline24, system-unavailability and emergency modes. It is issued separately and cannot authenticate an ERP or API session.

How does certificate authentication start in the KSeF API?

The flow starts with POST /auth/challenge. The client creates an AuthTokenRequest for the challenge and chosen context, applies an XAdES signature, submits it, and follows the documented exchange to obtain temporary authentication, access and refresh tokens for the session.

Does a KSeF certificate contain company permissions?

No. The certificate contains no company context and does not hold KSeF permissions. The login request identifies a context, and KSeF verifies server-side that the authenticated identity has at least one active permission in that context.

Can certificate enrollment be started after logging in with a KSeF token?

Certificate enrollment data can only be obtained after XAdES authentication, not authentication with a KSeF system token. Confirm the authorised person's supported XAdES route and access before making enrollment a dependency of the production schedule.

How can we test cutover without causing duplicate invoices?

Compare authentication and permission checks without duplicating submission, then route a controlled set of low-risk transactions through the certificate path. Reconcile KSeF status and references against ERP records, use idempotent retry controls, and inspect status before resending any uncertain transaction.

When should old KSeF token secrets be deleted?

Remove them after every known workload has passed certificate-path testing, production canary and the approved observation window. Verify no token endpoint calls remain, preserve non-secret evidence, and revoke or invalidate old tokens where supported—well before their support ends.

Key regulations, formats and terms

PolandKSeFKrajowy System e-FakturPolish Ministry of Financepodatki.gov.plstructured invoiceAPI authenticationinvoice correctionsaccounting softwareVATSMEecommerceEuropean CommissioneInvoicingEN 16931Directive 2014/55/EUstructured electronic invoiceVAT automationcross-border tradeKSeF token-to-certificate migration for ERP and API integrations

Poland — Country hub

Poland

Open country hub →

Use the country hub to see every related deadline, checklist, format guide and software comparison for this market.

Continue reading

Official sources

We prioritize official government and EU sources where available and keep last-checked dates visible for mandate-sensitive pages.