KSEF-21116:KSeF authentication token is invalid
Fix: Verify the token value character-for-character, confirm you are calling the correct environment (test vs production), and confirm the token was generated for the exact NIP context you are authenticating against.
KSeF error 21116 ("Nieprawidłowy token") is returned when the AuthorisationToken supplied to /online/Session/InitToken does not match a valid, active token issued for the target NIP context. Unlike 21170 (session expired) or 21302 (token inactive), 21116 means KSeF cannot recognise the token at all — wrong value, wrong environment, or wrong context.
Engine Classification
Financial or legal field · Modification blocked by policy
What is KSEF-21116?
KSEF-21116 is a fatal validation rule defined in the ksef specification (POL national rules). It validates the GenerateToken). Tokens are context-bound: a token generated for NIP A cannot authenticate for NIP B, and a token generated in the test environment cannot authenticate against production. The AuthorisationToken is included in the signed InitToken payload as base64-encoded plaintext. element under online > Credentials in the UBL invoice XML.
When this rule fires, the invoice is rejected by Peppol access points and never reaches the buyer.
Target path: KSeF supports two authentication paths: signed challenge (qualified electronic signature or personal seal) and token-based (a token issued via /online/Credentials/GenerateToken). Tokens are context-bound: a token generated for NIP A cannot authenticate for NIP B, and a token generated in the test environment cannot authenticate against production. The AuthorisationToken is included in the signed InitToken payload as base64-encoded plaintext.
Why This Error Matters
21116 during a rollout typically means the wrong secret is in the wrong environment — a low-severity misconfiguration that nevertheless blocks all invoice submission until fixed. Under mandatory KSeF, a production token that expires or is accidentally rotated causes an immediate outage for the affected NIP.
KSEF-21116 is a hard failure — the invoice must be corrected and re-sent before it can reach the recipient.
Blocks all authentication for the affected NIP context until the token is fixed or replaced. In mandatory-KSeF mode, this is a full invoicing outage for that NIP.
Validator Behavior
- ·Causes invoice rejection
- ·Error returned: KSEF-21116
- ·Specification: ksef
How to Fix It
XML Example
Generic example based on the rule's target XPath. Your actual XML structure may differ.
<!-- Triggers validation error --> <GenerateToken). Tokens are context-bound: a token generated for NIP A cannot authenticate for NIP B, and a token generated in the test environment cannot authenticate against production. The AuthorisationToken is included in the signed InitToken payload as base64-encoded plaintext.></GenerateToken). Tokens are context-bound: a token generated for NIP A cannot authenticate for NIP B, and a token generated in the test environment cannot authenticate against production. The AuthorisationToken is included in the signed InitToken payload as base64-encoded plaintext.>
<!-- Corrected --> <GenerateToken). Tokens are context-bound: a token generated for NIP A cannot authenticate for NIP B, and a token generated in the test environment cannot authenticate against production. The AuthorisationToken is included in the signed InitToken payload as base64-encoded plaintext.>VALID_VALUE</GenerateToken). Tokens are context-bound: a token generated for NIP A cannot authenticate for NIP B, and a token generated in the test environment cannot authenticate against production. The AuthorisationToken is included in the signed InitToken payload as base64-encoded plaintext.>
Technical Reference
KSeF supports two authentication paths: signed challenge (qualified electronic signature or personal seal) and token-based (a token issued via /online/Credentials/GenerateToken). Tokens are context-bound: a token generated for NIP A cannot authenticate for NIP B, and a token generated in the test environment cannot authenticate against production. The AuthorisationToken is included in the signed InitToken payload as base64-encoded plaintext.Code Example
const { credentialsList } = await ksefAdmin.get('/online/Credentials/List');
const tokenRecord = credentialsList.find(c =>
c.credentialsRole === 'invoice_write' &&
c.credentialsScope.contextIdentifier.value === targetNip &&
c.credentialsIdentifier === expectedTokenId
);
if (!tokenRecord) {
throw new Error(`Token ${expectedTokenId} not found for NIP ${targetNip} in ${env}`);
}Common Causes
- ·Test-environment token deployed to a production configuration (or vice versa).
- ·Token truncated during copy-paste through spreadsheets, chat, or logs that trim whitespace.
- ·Token was revoked by an admin in the KSeF portal without notifying the integration team.
- ·Wrong target NIP in InitToken payload — the token is valid, but for a different context.
- ·Token freshly generated and not yet propagated (rare, but possible within ~5 minutes of issuance).
- ·Base64 encoding applied twice or not at all in the InitToken request body.
Seeing this in production? The API handles KSEF-21116 automatically. See the fix response →
Commonly Seen In
Frequently Asked Questions
21116 = token unrecognized (wrong value, wrong environment, wrong context). 21302 = token exists but is inactive (not yet activated or explicitly deactivated). 21303 = token was revoked. All three block InitToken; the fix path differs.
No. Tokens are environment-scoped. Any token generated on ksef-test.mf.gov.pl will return 21116 when used against ksef.mf.gov.pl and vice versa.
Tokens do not have a fixed expiry — they remain valid until revoked. However, best practice is to rotate quarterly and to have at least two active tokens per NIP context so rotation can happen without downtime.
Yes — Invoice Navigator handles token generation, rotation, environment isolation, and revocation monitoring per NIP context. Your ERP integrates with one Invoice Navigator API key that never rotates.
Either the token was revoked (check /online/Credentials/List — you will see it in state Revoked or missing entirely), or you are inadvertently pointing at a different environment. Log the request host and Authorization header (redacted) on any 21116 to catch environment drift.
Related Errors
Related Content
Last updated: 28 July 2026
Validate your invoice
Drop your XML here to check for KSEF-21116
Detect KSEF-21116 before submission
This error involves a financial field that can't be auto-modified. We'll flag it with a clear diagnosis so you can fix it at the source.