Overview

When Two-Factor Authentication (2FA) is enabled in Kerio Connect (version 9.4 and later), administrators and developers may attempt to use an application password to authenticate against the JSON-RPC API (Session.login). The API rejects the application password with "Username or password is not correct", even though the same application password works with mail clients such as KOFF or IMAP.

This is expected behavior. Application passwords are scoped exclusively to mail-client and protocol-level access (KOFF, IMAP, and similar). They cannot be used for Webmail, WebAdmin, or any interface that relies on the same authentication layer — including the JSON-RPC API.

In This Article

• Symptoms
• Why Application Passwords Are Rejected by the API
• Correct Authentication Methods
• Additional Information
• FAQ

Symptoms

• A script or integration calls the Kerio Connect JSON-RPC API endpoint (e.g., /webmail/api/jsonrpc/ or /admin/api/jsonrpc/) using Session.login.
• 2FA is enabled for the account's domain.
• An application password (created in Webmail or Kerio Connect Client under Settings → App Passwords) is supplied as the password parameter.
• The API returns: "Username or password is not correct."
• The same script succeeds when the account's standard (primary) password is used instead.

Why Application Passwords Are Rejected by the API

Kerio Connect's application passwords were introduced in version 9.4 alongside 2FA. Their scope is intentionally limited:

• Designed for: KOFF, IMAP, POP3, SMTP, and similar mail-client or protocol-level connections.
• Not valid for: Webmail login, WebAdmin login, or the JSON-RPC API.

This restriction is a security feature. As documented in Mail Server Security:

"Compromised app passwords only impact a single assigned application and cannot be used for Webmail or Webadmin access."

The JSON-RPC API's Session.login method shares the Webmail/WebAdmin authentication layer. Because application passwords are explicitly blocked from that layer, the API rejects them.

Correct Authentication Methods

JSON-RPC API Access

Use the account's standard (primary) password with Session.login. Even when 2FA is enabled for the domain, the JSON-RPC API accepts the standard password without prompting for a 2FA code.

Example call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Session.login",
  "params": {
    "userName": "user@example.com",
    "password": "standard-account-password",
    "application": {
      "name": "MyApp",
      "vendor": "MyCompany",
      "version": "1.0"
    }
  }
}

Mail Client Access (KOFF, IMAP, POP3, SMTP)

Use the application password created in Webmail or Kerio Connect Client under Settings → App Passwords. Once 2FA is enabled, standard passwords no longer work for these protocols — application passwords are required.

Quick Reference

Access Method	Password Type	2FA Prompt?
JSON-RPC API (Session.login)	Standard password	No
Webmail (browser login)	Standard password	Yes
WebAdmin (browser login)	Standard password	Yes
KOFF / IMAP / POP3 / SMTP	Application password	No

Additional Information

• Application passwords were introduced in Kerio Connect 9.4 specifically for KOFF, IMAP, and similar use cases — to support non-interactive clients after enabling 2FA. See
• For a comprehensive overview of authentication methods, 2FA configuration, and application password management, see: Mail Server Security.
• Application passwords are generated automatically by the system and cannot be changed after creation. If lost, delete the old password and create a new one from Settings → App Passwords in Webmail or Kerio Connect Client.
• When using API automation on accounts with 2FA enabled, ensure the standard password is stored securely (e.g., in a secrets vault), since it provides Webmail-level access.

FAQ

Q1: Is it a bug that the JSON-RPC API rejects my application password?
A1: No. This is expected behavior by design. Application passwords are scoped to mail-client protocols (KOFF, IMAP, POP3, SMTP) and are intentionally blocked from the Webmail/WebAdmin authentication layer, which includes the JSON-RPC API.

Q2: If 2FA is enabled, why doesn't the API ask for a 2FA code when I log in with the standard password?
A2: The JSON-RPC API's Session.login method does not enforce the interactive 2FA prompt. The 2FA challenge applies to browser-based logins (Webmail and WebAdmin) and Kerio Connect Client. API calls using the standard password authenticate without a second factor.

Q3: Can I create a dedicated application password specifically for API access?
A3: No. Application passwords in Kerio Connect are restricted to mail-client protocols. For API access, you must use the account's standard password. Consider using a dedicated service account with a strong, unique password stored in a secrets manager to limit exposure.