Translation. Original: tokeny-ksef.md

KSeF Token Management

29.06.2025

A KSeF token is a unique, generated authentication identifier that — alongside qualified electronic signature — enables authentication to the KSeF API.

A KSeF token is issued with an immutable set of permissions defined during its creation; any modification of these permissions requires generating a new token.

Note!
The KSeF token serves as a confidential authentication secret — it should be stored exclusively in a trusted and secure repository.

Prerequisites

Generation of a KSeF token is only possible after one-time authentication with an electronic signature (XAdES).

1. Token Generation

A token can only be generated within the context of Nip or InternalId. Generation is performed by calling the endpoint:
POST /tokens

Providing a collection of permissions and token description in the request body.

Implementation Examples:

Field	Example Value	Description
Permissions	["InvoiceRead", "InvoiceWrite", "CredentialsRead", "CredentialsManage"]	List of permissions assigned to the token
Description	"Token for reading invoices and account data"	Token description

C# example: KSeF.Client.Tests.Core\E2E\KsefToken\KsefTokenE2ETests.cs

 KsefTokenRequest tokenRequest = new KsefTokenRequest
    {
        Permissions = [
            KsefTokenPermissionType.InvoiceRead,
            KsefTokenPermissionType.InvoiceWrite
            ],
        Description = "Demo token",
    };
 KsefTokenResponse token = await ksefClient.GenerateKsefTokenAsync(tokenRequest, accessToken, cancellationToken);

Java example: KsefTokenIntegrationTest.java

KsefTokenRequest request = new KsefTokenRequestBuilder()
        .withDescription("test description")
        .withPermissions(List.of(TokenPermissionType.INVOICE_READ, TokenPermissionType.INVOICE_WRITE))
        .build();
GenerateTokenResponse ksefToken = ksefClient.generateKsefToken(request, authToken.accessToken());

2. Token Filtering

KSeF token metadata can be retrieved and filtered using the call:
GET /tokens

C# example: KSeF.Client.Tests.Core\E2E\KsefToken\KsefTokenE2ETests.cs

QueryKsefTokensResponse singleResult = await KsefClient.QueryKsefTokensAsync(
    AccessToken,
    statuses: new List<AuthenticationKsefTokenStatus> {
        AuthenticationKsefTokenStatus.Pending,
        AuthenticationKsefTokenStatus.Active,
        AuthenticationKsefTokenStatus.Revoking,
        AuthenticationKsefTokenStatus.Revoked,
        AuthenticationKsefTokenStatus.Failed
    }, // default: null
    authorIdentifier: "authorIdentifier", // default: null
    authorIdentifierType: AuthenticationTokenContextIdentifierType.Nip, // or other type, default: null
    description: "description",
    continuationToken: continuationToken,
    pageSize: pageSize, // default: null
    cancellationToken: cancellationToken // default null,
    );

Java example: KsefTokenIntegrationTest.java

List<AuthenticationTokenStatus> status = List.of(AuthenticationTokenStatus.ACTIVE);
Integer pageSize = 10;
QueryTokensResponse tokens = ksefClient.queryKsefTokens(status, StringUtils.EMPTY, null, null, null, pageSize, accessToken);

The response returns token metadata, including information about who generated the KSeF token and in what context, as well as the permissions assigned to it.

3. Retrieving a Specific Token

To retrieve details of a specific token, use the call:
GET /tokens/{referenceNumber}

referenceNumber is the unique token identifier that can be obtained during its creation or from the token list.

C# example: KSeF.Client.Tests.Core\E2E\KsefToken\KsefTokenE2ETests.cs

AuthenticationKsefToken token = await ksefClient.GetKsefTokenAsync(referenceNumber, accessToken, cancellationToken);

Java example: KsefTokenIntegrationTest.java

AuthenticationToken ksefToken = ksefClient.getKsefToken(token.getReferenceNumber(), accessToken);

4. Token Revocation

To revoke a token, use the call:
DELETE /tokens/{referenceNumber}

referenceNumber is the unique identifier of the token we want to revoke.

C# example: KSeF.Client.Tests.Core\E2E\KsefToken\KsefTokenE2ETests.cs

await ksefClient.RevokeKsefTokenAsync(referenceNumber, accessToken, cancellationToken);

Java example: KsefTokenIntegrationTest.java

ksefClient.revokeKsefToken(token.getReferenceNumber(), accessToken);