Configure KSeF tokens (alternative)

Learn how to configure Krajowy System e-Faktur (KSeF)2.0 tokens for authentication.

Note:

KSeF 2.0 Tokens are required. KSeF 1.0 tokens are incompatible with KSeF 2.0. You must generate new KSeF 2.0 tokens; old tokens cannot be migrated or reused.

Tokens were previously scheduled for deprecation on January 1, 2027. Poland's Ministry of Finance has reversed this decision and confirmed that tokens have no planned end date. Migration to certificates is optional; if you choose to migrate, see Migrate from tokens to certificates.

Create separate configurations for:

Outbound configuration: Invoice submission (pl_Faktura__2.0)
Inbound configuration: Invoice polling (pl_Faktura_Polling_2.0)

Use the same token for both directions; only the productId differs.

Note:

If you need to perform multiple operations, create separate configurations for submission and polling. Use the same token for both.

Tokens reference

Krajowy System e-Faktur (KSeF) tokens are alphanumeric authentication strings that enable API access to KSeF for online invoice submission.

Token format

KSeF 2.0 tokens are structured strings with three parts separated by pipes (|).
Format: [session-data]|nip-[NIP]|[hash]
Typical length: 150-200 characters

Token property reference

When you configure your tokens in Sovos, use the appropriate properties:


Token	Format	Required property
KSeF Token (Alternative)	String	authorizationToken

API endpoint

POST https://api-test.sovos.com/v2/configurations/organizations/{orgId}/settings
Authorization: Bearer {accessToken}
Content-Type: application/json

Environment URLs

Test: https://api-test.sovos.com
Production: https://api.sovos.com

Key parameters

Every token configuration must include these scope parameters:

authorizationToken: Complete token string from KSeF portal (3 pipe-separated parts, 150-200 characters)
operation: "Issue" for invoice submission or "Validate" for polling.
category: Always PL_INV for Poland
productId: pl_Faktura__2.0 (submission) or pl_Faktura_Polling_2.0 (polling)
workspaceId: Your Sovos workspace identifier
orgId: Your Sovos organization identifier
taxId: Your 10-digit NIP (optional but recommended)

Token limitations

Tokens cannot support offline mode. Offline invoice issuance uses certificate-based authentication (Type 1 for KSeF API access) AND Type 2 certificates for QR code generation. Offline mode needs switching entirely to certificates.

Other restrictions:

No batch transmission support
Online real-time submission only

For offline or batch capabilities, migrate to certificates.

Outbound configuration

Learn how to configure outbound settings for invoice submission using Sovos.

Generate KSeF tokens (alternative)

Important:

Tokens are not compatible with offline mode and batch transmission. Sovos doesn't currently support batch transmission.

Call the configuration endpoint using a POST request.

Read more about the configuration API in the API reference.

POST https://api-test.sovos.com/v2/configurations/organizations/{orgId}/settings
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "value": {
    "authorizationToken": "[YOUR_KSEF_2.0_TOKEN]"
  }
}

Your request must include the key parameters, according to your configuration.

This example shows the structure for your token configuration.

Note:

Configure token for invoice submission using operation: "Issue" and productId: "pl_Faktura__2.0 for outbound processing.

{
  "name": "partner_credentials_KSEF_V2",
  "value": {
    "authorizationToken": "[YOUR_KSEF_2.0_TOKEN]"
  },
  "scope": {
    "operation": "Issue",
    "category": "PL_INV",
    "productId": "pl_Faktura__2.0",
    "orgId": "[YOUR_ORG_ID]",
    "taxId": "[YOUR_TAX_ID]",
    "workspaceId": "[YOUR_WORKSPACE_ID]"
  }
}

After completing these steps, you have the credentials needed to submit invoices to KSeF through Sovos.

Inbound configuration

Learn how to configure outbound settings for invoice polling using Sovos.

Generate KSeF tokens (alternative)

Important:

Tokens are not compatible with offlinemode and batch transmission. Currently, Sovos doesn't offer support to batch transmission.

Key differences from outbound:

operation: Changes to "Validate" for polling.
productId: Changes to "pl_Faktura_Polling_2.0".
authorizationToken: Use same token as outbound configuration.
Configuration: Create separate configuration (different API call).

Call the configuration endpoint using a POST request.

Read more about the configuration API in the API reference.

POST https://api-test.sovos.com/v2/configurations/organizations/{orgId}/settings
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "value": {
    "authorizationToken": "[YOUR_KSEF_2.0_TOKEN]"
  }
}

Your request must include the key parameters, according to your configuration.

This example shows the structure for your token configuration.

Note:

Configure the same token for invoice status polling using operation: "Validate" and productId: "pl_Faktura_Polling_2.0" for polling.

{
  "name": "partner_credentials_KSEF_V2",
  "value": {
    "authorizationToken": "[SAME_TOKEN_AS_OUTBOUND]"
  },
  "scope": {
    "operation": "Validate",
    "category": "PL_INV",
    "productId": "pl_Faktura_Polling_2.0",
    "orgId": "[YOUR_ORG_ID]",
    "taxId": "[YOUR_TAX_ID]",
    "workspaceId": "[YOUR_WORKSPACE_ID]"
  }
}

After completing these steps, you have the credentials needed to get invoices through Sovos.

Troubleshooting

This section offers solutions to common problems encountered during tokens configuration.

Error: "Invalid token" or "Authentication failed"

Common causes

Using KSeF 1.0 token (must be KSeF 2.0)
Token revoked or expired
Wrong environment (test token in production)
Incorrect scope parameters (wrong taxId, orgId, productId)

Solutions

Verify token generated after December 10, 2025
Check token not revoked in Token List
Match environment: test token → test endpoint, prod token → prod endpoint
Copy token exactly (no spaces or formatting changes)
Verify scope parameters match your setup
Generate new token if problems persist

Error: HTTP 403 - Forbidden

Causes

Insufficient permissions, rate limiting

Solutions

Verify token permissions
Wait 60+ seconds if rate limited
Check operation matches token capabilities

Error: Token format validation fails

Common causes

Token string copied incorrectly (missing characters or line breaks introduced)
Token truncated during copy/paste
Extra spaces or formatting added to token string
Token missing one or more pipe separators (|)
Incomplete hash in third section

Solution

Verify token contains three parts separated by pipes (|), NIP appears in middle section, complete hash in third section.

Operation/Product ID Mismatch

Common causes

Using operation: "Issue" with productId: "pl_Faktura_Polling_2.0".
Using operation: "Validate" with productId: "pl_Faktura__2.0".
Copying configuration between outbound and inbound without updating both parameters.

Solution

Outbound (submission): Use operation: "Issue" with productId: "pl_Faktura__2.0".
Inbound (polling): Use operation: "Validate" with productId: "pl_Faktura_Polling_2.0".
Always verify both parameters match the intended direction.

How can we help?

Configure KSeF tokens (alternative)

Tokens reference

API endpoint

Environment URLs

Key parameters

Token limitations

Outbound configuration

Inbound configuration

Troubleshooting

Error: "Invalid token" or "Authentication failed"

Error: HTTP 403 - Forbidden

Error: Token format validation fails

Operation/Product ID Mismatch

sovos-footer