What a KSeF token is
A KSeF token is a secret string that the taxpayer generates in the Ministry of Finance application. Software uses it to log in to the KSeF API on behalf of a company (identified by its NIP) with the permissions chosen when the token was created. It replaces a qualified signature on every login, which is what makes automated invoicing possible.
Testing Notaly? You do not need a token. Sandbox accounts submit to KSeF TEST with Notaly's test credentials (seller NIP 2745013933). You only need your own token when you move to a paid plan.
Before you start
- Pick the environment. Tokens only work in the environment where they were created: TEST (
ap-test.ksef.mf.gov.pl, fictitious data), DEMO (ap-demo.ksef.mf.gov.pl, real credentials, no legal effect) or PRODUCTION (ap.ksef.mf.gov.pl). - Have a way to log in. The application accepts the Trusted Profile (Profil Zaufany), a qualified electronic signature or a qualified seal, or an e-ID card (e-dowód).
- Have the right to grant permissions. You must be the company owner or hold the permission to manage credentials for that NIP.
Generate the token, step by step
- Open the KSeF applicationGo to the Ministry of Finance KSeF application for your environment (Aplikacja Podatnika KSeF, Certificates and Permissions Module) and log in for the company's NIP.
- Go to tokensOpen the token section and choose to generate a new token. Give it a name you will recognise later, for example
Notaly API. - Choose the permissionsSelect at least issuing invoices (
InvoiceWrite). Add viewing invoices (InvoiceRead) if you also want to read invoices from KSeF. Do not grant permission management unless you need it. - Generate and copy it nowKSeF shows the token only once. Copy it straight into a password manager or into Notaly. If you lose it, revoke it and generate a new one.
Treat the token like a password. Anyone who has it can issue invoices in your company's name. Never put it in email, tickets, chat or source code.
Connect the token to Notaly
- Open your dashboardLog in at /login and open Settings → KSeF connection.
- Enter NIP, token and environmentUse the same NIP you logged in with and the environment where the token was generated.
- ConnectNotaly logs in to KSeF right away with your token (challenge plus RSA-OAEP encryption). When it succeeds, the connection is active and your invoices are issued with your NIP as the seller.
Connecting your own token is part of the paid plans (Starter €49/month, Scale €199/month), and the Connect KSeF screen is rolling out together with production access. A paid plan takes effect once your KSeF connection is validated.
How Notaly stores your token
- The token is encrypted with AES-256-GCM, bound to your account, NIP and environment, and is never shown again, not even to our support team.
- It is decrypted only for the moment of logging in to KSeF and never written to logs.
- Disconnect in the dashboard deletes the encrypted token. Also revoke it in the KSeF application.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Connection is invalid | Token revoked, mistyped or from another environment | Generate a new token in the right environment and reconnect |
| KSeF refuses the login | Token NIP differs from the NIP you entered | Use the NIP you logged in with when creating the token |
| Invoices rejected for permissions | Token lacks InvoiceWrite | Generate a token with permission to issue invoices |
| Worked in TEST, fails in production | Environments are separate | Generate a production token at ap.ksef.mf.gov.pl |
Still stuck? Open a ticket from the support form. Describe the error, but never include the token itself.