Legacy OCPP Behavior

1. Overview

When configuring an installation to use OCPP-J 1.6 authentication, the behavior depends on whether the OCPP URL is set at the charger level or installation level.

If no charger-level URL is set, the charger uses the installation-level URL template with a {deviceId} placeholder. This is automatically replaced with the charger’s Device ID.

Example:

wss://some.demo.server:443/zaptec/{deviceId}

becomes

wss://some.demo.server:443/zaptec/ZAPP12345

Note: The legacy setting only applies when a charger-level URL is defined. If only the installation-level URL is used, the charger will follow the template defined in the installation settings and always use its Device ID as the identity for basic authentication.

2. Legacy OCPP Behavior

With legacy behavior enabled, Zaptec always uses the charger’s Device ID as the username in basic authentication, regardless of how the charger-level OCPP URL is constructed (even if it includes a custom identifier such as OcppNameId).

This setting only takes effect when a charger-level OCPP URL is defined. If not, the charger falls back to the installation-level URL template, replacing {deviceId} with the actual Device ID, and uses that Device ID for authentication.

Example: For charger ZAPP12345 with a charger-level OCPP URL like:

wss://host/ocpp/Zaptec-OcppNameId

If legacy behavior is enabled, the username used for basic authentication will still be:

ZAPP12345

3. Identity Resolution Behavior (OCPP 1.6J Standard - Default)

This section describes the default behavior according to the OCPP 1.6J standard, which applies to all new installations unless explicitly configured to use legacy behavior.

This logic only applies when a custom OCPP URL is defined at the charger level. If not, the charger uses the installation-level template URL.

3.1 No charger-level URL defined

• The charger uses the installation-level URL template.
• The {deviceId} placeholder is replaced with the charger’s Device ID.
• The Device ID is used as the username for basic authentication.

3.2 Charger-level URL is defined

• The charger uses the URL exactly as defined.

• The username for basic authentication is:

  • The last segment of the URL path, if the path has more than two segments.
  • The Device ID, if the path has two or fewer segments.

Code logic:

private static string GetDeviceIdFromUrlOrDefault(Uri url, string defaultDeviceId)
{
    // If the url doesn't contain a path, we default to the device id as identity
    return url.Segments.Length < 2 ? defaultDeviceId : HttpUtility.UrlDecode(url.Segments.Last());
}

4. Switching Behavior

To change the identity format for an installation:

1. Open the relevant Installation in the Zaptec Portal.

2. Go to Authentication settings.

3. Use the toggle "Use legacy OCPP behavior":

   • Disabled - Uses OCPP 1.6J standard format (recommended)
   • Enabled - Uses the legacy Zaptec identity format (Device ID)

5. Summary Table