KSEF-21301:Missing authorization for this KSeF operation
Fix: Verify that the required KSeF authorization (invoice_write, samofakturowanie, or the specific role the endpoint requires) has been granted on the target NIP context and that the grant is still within its validity window. Grants take up to 15 minutes to propagate after issuance.
KSeF error 21301 ("Brak autoryzacji") is returned when the authenticated token has no permission to perform the requested action in the current NIP context. The most common trigger is attempting to issue a self-billing invoice (samofakturowanie) without an active samofakturowanie authorization on the seller's NIP, but any missing permission — invoice-write, credentials-manage, tax-representative — surfaces the same code.
Engine Classification
Financial or legal field · Modification blocked by policy
What is KSEF-21301?
KSEF-21301 is a fatal validation rule defined in the ksef specification (POL national rules). It validates the KSeF enforces a role-based permission model per NIP context. Each authorization is a signed grant recorded in KSeF that maps (grantor NIP → grantee identifier → role → validity window). Roles include invoice_read, invoice_write, credentials_read, credentials_manage, subunit_manage, and role-specific ones like samofakturowanie (self-billing) and tax_representative. 21301 fires when the caller's session has no matching active grant for the operation. element 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 enforces a role-based permission model per NIP context. Each authorization is a signed grant recorded in KSeF that maps (grantor NIP → grantee identifier → role → validity window). Roles include invoice_read, invoice_write, credentials_read, credentials_manage, subunit_manage, and role-specific ones like samofakturowanie (self-billing) and tax_representative. 21301 fires when the caller's session has no matching active grant for the operation.
Why This Error Matters
Missing authorization blocks invoicing entirely for the affected relationship. Under mandatory KSeF, a self-billing arrangement that worked before the switchover but was never formally granted in KSeF fails on the first attempt with 21301 — and there is no fallback path. Getting a grant issued involves the seller's authorized signatory, which can take days if the relationship is not pre-arranged.
KSEF-21301 is a hard failure — the invoice must be corrected and re-sent before it can reach the recipient.
Blocks the specific operation entirely. In self-billing setups, blocks the entire buyer-seller invoice flow until a grant is issued.
Validator Behavior
- ·Causes invoice rejection
- ·Error returned: KSEF-21301
- ·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 --> <KSeF enforces a role-based permission model per NIP context. Each authorization is a signed grant recorded in KSeF that maps (grantor NIP → grantee identifier → role → validity window). Roles include invoice_read, invoice_write, credentials_read, credentials_manage, subunit_manage, and role-specific ones like samofakturowanie (self-billing) and tax_representative. 21301 fires when the caller's session has no matching active grant for the operation.></KSeF enforces a role-based permission model per NIP context. Each authorization is a signed grant recorded in KSeF that maps (grantor NIP → grantee identifier → role → validity window). Roles include invoice_read, invoice_write, credentials_read, credentials_manage, subunit_manage, and role-specific ones like samofakturowanie (self-billing) and tax_representative. 21301 fires when the caller's session has no matching active grant for the operation.>
<!-- Corrected --> <KSeF enforces a role-based permission model per NIP context. Each authorization is a signed grant recorded in KSeF that maps (grantor NIP → grantee identifier → role → validity window). Roles include invoice_read, invoice_write, credentials_read, credentials_manage, subunit_manage, and role-specific ones like samofakturowanie (self-billing) and tax_representative. 21301 fires when the caller's session has no matching active grant for the operation.>VALID_VALUE</KSeF enforces a role-based permission model per NIP context. Each authorization is a signed grant recorded in KSeF that maps (grantor NIP → grantee identifier → role → validity window). Roles include invoice_read, invoice_write, credentials_read, credentials_manage, subunit_manage, and role-specific ones like samofakturowanie (self-billing) and tax_representative. 21301 fires when the caller's session has no matching active grant for the operation.>
Technical Reference
KSeF enforces a role-based permission model per NIP context. Each authorization is a signed grant recorded in KSeF that maps (grantor NIP → grantee identifier → role → validity window). Roles include invoice_read, invoice_write, credentials_read, credentials_manage, subunit_manage, and role-specific ones like samofakturowanie (self-billing) and tax_representative. 21301 fires when the caller's session has no matching active grant for the operation.Code Example
const { credentialsList } = await ksef.get('/online/Credentials/List');
const hasSelfBilling = credentialsList.some(c =>
c.credentialsRole === 'samofakturowanie' &&
c.credentialsScope.contextIdentifier.value === sellerNip &&
new Date(c.credentialsValidFrom) <= new Date() &&
(c.credentialsValidTo === null || new Date(c.credentialsValidTo) > new Date())
);
if (!hasSelfBilling) {
throw new Error(
`Self-billing not authorized on ${sellerNip}. ` +
`Ask the seller to grant samofakturowanie to NIP ${issuerNip}.`
);
}Common Causes
- ·Self-billing (samofakturowanie) attempted without a formal grant from the seller — the pre-KSeF written agreement does not carry over automatically.
- ·Grant was issued but is still propagating (< 15 min old).
- ·Grant expired — grants can have a credentialsValidTo date, and the operation is being attempted after it.
- ·Grant issued to the wrong identifier — e.g., natural person PESEL instead of the technical token's NIP.
- ·Tax representative operation attempted without the tax_representative role.
- ·Attempting to read credentials on a NIP where the token has invoice_read but not credentials_read.
Seeing this in production? The API handles KSEF-21301 automatically. See the fix response →
Commonly Seen In
Frequently Asked Questions
No — an invalid token returns 21116 or 21302. 21301 means the token authenticated successfully but has no permission for the operation. Fix the grant, not the token.
The Ministry of Finance documents propagation as up to 15 minutes — in practice most grants are active within 2-3 minutes. If a grant is over an hour old and still failing, verify the grant was issued to the correct identifier (NIP vs PESEL) and role.
No — grants must be issued by an authorized signatory on the grantor's KSeF account, either through the Taxpayer Application portal or a signed /online/Credentials/Generate request. Invoice Navigator surfaces which grant is missing so you can request it from the correct counterparty.
KSeF 2.0 requires an explicit samofakturowanie credential registered in KSeF. Pre-2.0 arrangements based on paper agreements are not auto-migrated. Both parties must re-establish the grant in KSeF before self-bills will be accepted.
invoice_write authorizes submitting invoices where the granting NIP is the SELLER. It does not authorize self-billing (samofakturowanie) or credentials management. If you need to submit as buyer on the seller's behalf, you need samofakturowanie, not invoice_write.
Related Errors
Related Content
Last updated: 28 July 2026
Validate your invoice
Drop your XML here to check for KSEF-21301
Detect KSEF-21301 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.