Authentication methods

Authentication is the step that turns a root Client or AsyncClient into an authenticated client for one KSeF context. The root client chooses the environment and owns transport resources. The authentication method proves who may operate in the selected context.

KSeF separates two ideas that are easy to merge mentally:

After authentication succeeds, the SDK returns an AuthenticatedClient. That client carries KSeF access and refresh tokens and exposes protected branches such as sessions, invoices, tokens, permissions, certificates, limits, and session history.

Client(Environment.TEST)
  -> client.authentication
    -> with_token(), with_xades(), with_test_certificate(), or with_profile()
      -> AuthenticatedClient for one KSeF context
        -> online sessions, batch sessions, invoices
        -> tokens, permissions, certificates, limits

KSeF methods and SDK helpers

At the KSeF API level, authentication has two main families:

The SDK adds two convenience layers:

Choose a method

See also:

• Configure authentication: Use the selected method in runnable SDK code with environment variables and secret boundaries.
• Use profiles: Share CLI-compatible local authentication settings between command-line and SDK workflows.

XAdES subject and context

For XAdES authentication, the SDK builds and signs the XML request for the context NIP you pass to with_xades(). KSeF reads the authenticating subject from the signing certificate: for example a company seal certificate, a personal certificate containing a NIP or PESEL, a KSeF authentication certificate, or a certificate allowed by fingerprint permissions.

That means nip is the login context, not necessarily the identifier embedded in the signing certificate. A person can authenticate into a company context if KSeF sees the right active permissions for that person or certificate.

Access tokens refresh themselves

KSeF access tokens are short-lived. The authenticated client therefore keeps the refresh token next to the access token and renews the access token without your code doing anything: shortly before access_token_valid_until, and once after a 401 response, retrying the failed request a single time. Concurrent requests share one refresh.

This covers every way of getting an authenticated client: the with_* login methods and client.authentication.resume(state), which accepts the state object or its JSON string. A state whose access token has expired works as long as its refresh token is still valid. Session handles resumed with state= use the same client, so they refresh too. auth.resume_state() and auth.auth_tokens return the current tokens, so save the state again after long-running work.

When the refresh token is expired or rejected, the client raises KSeFAuthenticationExpiredError, which subclasses KSeFAuthError. Authenticate again to continue. To refresh tokens yourself, pass TransportConfig(auto_refresh_tokens=False). See the Operations reference for the exact rules.

Profiles are local authentication configuration

with_profile() is not a separate credential type. It is a configuration layer over the same authentication methods:

A profile stores non-secret settings such as environment, NIP, auth type, certificate paths, polling settings, and the name of the environment variable that contains a secret. It should not store token values, private-key passwords, or PKCS#12 passwords.

Profile selection follows the same order in the SDK and CLI:

1. Explicit profile name passed to with_profile("name").
2. KSEF2_PROFILE.
3. active_profile in the local profile config.

The root client environment must match the selected profile environment. A test profile belongs with Client(Environment.TEST), a demo profile with Client(Environment.DEMO), and a production profile with Client(Environment.PRODUCTION).

Authentication lifecycle

1. The root client requests a challenge from the selected KSeF environment.

2. The chosen method proves identity for the requested context.

   Token authentication encrypts the KSeF token together with the challenge timestamp. XAdES authentication signs the challenge XML. TEST certificate authentication generates TEST certificate material first. Profile authentication resolves one of those paths from local configuration.

3. KSeF starts an asynchronous authentication operation.

   The SDK keeps the temporary operation token and reference number internally while it polls for completion.

4. The SDK redeems the completed operation into access and refresh tokens.

5. The returned AuthenticatedClient carries those tokens into protected SDK operations.

Async clients use the same method names on AsyncClient; call them with await. The choice between token, TEST certificate, XAdES, and profile authentication stays the same.

What to protect

Keep secrets in environment variables, secret managers, or application-owned secure storage. Keep profile files limited to non-secret defaults and the names of environment variables that contain secrets.

Authentication is not authorization

Authentication proves identity for a context. Permissions still determine which operations that identity may perform. A credential can authenticate correctly and still fail when sending invoices, querying metadata, managing tokens, or granting permissions.

Related pages

• Authenticate: Configure environment variables, token auth, XAdES auth, TEST certificates, and profiles.
• Use profiles: Share local ksef2-cli profile configuration with SDK authentication and ProfileStore.
• Low-level authentication: Run the authentication operation manually when another system signs XML or owns token exchange.
• CLI authentication: Use the same profile-backed authentication methods from ksef2-cli.
• Tokens and permissions: Understand how authentication credentials and protected permissions fit together.
• XAdES: Understand certificate-backed XML signing during authentication.