OCPP 2.0.1 CSMS Server API

Complete developer guide and payload reference for the OCPP 2.0.1 Central Services Management System (CSMS).

Hybrid Architecture: The CSMS handles concurrent client WebSocket links from chargers, while hosting an HTTP REST API to allow remote control commands from external apps.
Default Port Configurations
Interface Protocol / Path Port Access Scope
WebSocket (CP Connection) ws://<host>/csms2/<chargePointId> (Profile 1)
wss://<host>/csms2/<chargePointId> (Profile 2 & 3)
9779 Charge Point Handshake (subprotocol ocpp2.0.1)
HTTP REST API POST /remote 9779 Internal Systems / Admin Controls
OCPP 2.0.1 Security Profiles

The CSMS fully supports the OCA Security Extensions and provides three communication profiles:

  • Security Profile 1 (Basic Auth): Unencrypted WebSocket connection using basic authentication credentials verified during connection handshake. Rejects connections on credential expiry (90 days configurable).
  • Security Profile 2 (Server TLS + Basic Auth): Secure WebSocket connection wrapped in TLS (using wss://). Enforces connection encryption via proxy headers or scheme verification, rejecting unsecure connection attempts with a 400 Bad Request. Chargers authenticate using hashed credentials stored in the CSMS database. Supports account lockout (15-minute freeze after 5 successive bad attempts), configurable password expiry (rejects connections on stale credentials), and administrative password rotation/generation.
  • Security Profile 3 (mTLS + Basic Auth + Fingerprint Binding): Mutual TLS WebSocket connection where both the server and client certificates are validated. In addition to certificate verification, the charger must authenticate using basic credentials (username and password) checked during the connection handshake. Enforces connection encryption, rejecting unsecure connection attempts. The CSMS verifies the client certificate signature chain against the configured Root/Intermediate CA, validates dates (checking expiry), checks revocation status using Certificate Revocation Lists (CRL) dynamically loaded from the certificate's Distribution Points, confirms the CN/SAN matches the target charger ID, and calculates its SHA-256 fingerprint to verify the database fingerprint binding. Rejection details (e.g. CERTIFICATE_EXPIRED, CERTIFICATE_REVOKED, CERTIFICATE_HOSTNAME_MISMATCH, CERTIFICATE_UNTRUSTED_CA) are audited individually.

WebSocket Protocol Frame Layout

All frames streaming over the WebSocket connection use the JSON-J frame structure defined by the OCPP specification:

JSON Frame Schema
[ <messageTypeId>, "<uniqueMessageId>", "<action>", <payload> ]
Element Type Value / Range Description
messageTypeId Integer 2 (Call), 3 (CallResult), 4 (CallError) Specifies the frame execution type.
uniqueMessageId String UUID/Auto-increment String Correlates requests with response acknowledgements.
action String OCPP Message Action Name Only present in Call (type 2) frames.
payload Object JSON object Action-specific data payload contents.

RequestStartTransaction (Remote Start)

Triggers a remote transaction start on a connected Charge Point.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "RequestStartTransaction",
  "payload": {
    "idTag": "abc",
    "connectorId": 1
  }
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "RequestStartTransaction").
payload Object Required Object containing the request parameters.
payload.idTag String Required The authorization ID token (RFID tag string, e.g. "abc") to start charging.
payload.connectorId Integer Optional The connector index on the EVSE. Defaults to 1.

RequestStopTransaction (Remote Stop)

Stops an active charging transaction remotely.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "RequestStopTransaction",
  "payload": {
    "transactionId": "tx-123"
  }
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "RequestStopTransaction").
payload Object Required Object containing the request parameters.
payload.transactionId String Required The unique identifier of the active transaction to stop.

Reset (Reboot)

Commands the Charge Point to perform a hardware reset.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "Reset",
  "payload": {
    "type": "Immediate"
  }
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "Reset").
payload Object Required Object containing the request parameters.
payload.type String Required The reset execution type: Immediate (Hard reset) or OnIdle (Soft reset).

UnlockConnector

Force unlocks a physical socket connection on an EVSE.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "UnlockConnector",
  "payload": {
    "evseId": 1,
    "connectorId": 1
  }
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "UnlockConnector").
payload Object Required Object containing the request parameters.
payload.connectorId Integer Required The target connector index to unlock.
payload.evseId Integer Optional The EVSE containing the connector. Defaults to 1.

ChangeAvailability

Modifies operational statuses on connector/EVSE hardware components.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "ChangeAvailability",
  "payload": {
    "connectorId": 1,
    "type": "Inoperative"
  }
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "ChangeAvailability").
payload Object Required Object containing the request parameters.
payload.connectorId Integer Required The connector index on the EVSE to change availability. Use 0 for the entire Charge Point.
payload.type String Required The target availability state: Operative or Inoperative.

ClearCache

Clears the local authorization cache tables stored inside the Charge Point.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "ClearCache",
  "payload": {}
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "ClearCache").
payload Object Required Empty object {}. No additional parameters required.

GetVariables / SetVariables

Queries or modifies internal configuration variables inside the Charge Point device.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "GetVariables",
  "payload": {
    "key": "AuthCtrlr.Enabled"
  }
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "GetVariables" or "SetVariables").
payload Object Required Object containing the request parameters.
payload.key String Required The dot-notation variable key string (e.g. "AuthCtrlr.Enabled").
payload.value String Required (Set only) The attribute value string to assign (only required for SetVariables).

SendLocalList

Sends an authorization list version updates to the local database of the Charge Point.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "SendLocalList",
  "payload": {
    "listVersion": 2,
    "updateType": "Full",
    "localAuthorizationList": [
      {
        "idTag": "abc",
        "idTagInfo": {
          "status": "Accepted"
        }
      }
    ]
  }
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "SendLocalList").
payload Object Required Object containing the request parameters.
payload.listVersion Integer Required The version number of this local authorization list. Must be positive.
payload.updateType String Required The list update type execution: Full (Overwrite list) or Differential (Patch list updates).
payload.localAuthorizationList Array of Objects Optional List of credentials consisting of:
  • idTag (String): The token identifier string (e.g. RFID value).
  • idTagInfo (Object): Auth validation metadata (e.g. status Accepted).

GetLocalListVersion

Requests the current version number of the local authorization list from the Charge Point.

POST /remote
{
  "chargePointId": "tn001_cs001_cp001",
  "action": "GetLocalListVersion",
  "payload": {}
}
Field Type Status Description
chargePointId String Required The unique identifier of the target Charge Point (e.g. "tn001_cs001_cp001").
action String Required The OCPP action name to execute (must match "GetLocalListVersion").
payload Object Required Empty object {}. No additional parameters required.

GetSecurityLogs

Queries the recent security audit logs for a specific charger. Tracks access failures, lockout incidents, and certificate status changes.

GET /remote/security-logs?chargePointId=<chargePointId>
HTTP JSON Response Array
[
  {
    "id": 1,
    "chargePointId": "tn001_cs001_cp001",
    "event": "INVALID_PASSWORD_ATTEMPT",
    "severity": "WARN",
    "timestamp": "2026-07-03T11:00:00Z",
    "details": "Invalid password check from remote IP: 127.0.0.1"
  }
]

Rotate Credentials

Rotates the Basic Auth credentials hash in the database for a specific charger.

POST /remote/credentials/rotate?chargePointId=<id>&password=<password>
HTTP Response Status
"Credentials rotated successfully"

Generate Credentials

Generates a cryptographically secure random password, updates the Basic Auth hash in the database, sets the update timestamp, and returns the raw password in the response.

POST /remote/credentials/generate?chargePointId=<id>
HTTP Response (Plaintext Password)
"aB3dE5fG7hI9jK1lM3nO5pQ7"

Bind Fingerprint

Associates the client certificate's SHA-256 fingerprint value in the database to enable mutual TLS connections (Profile 3).

POST /remote/credentials/bind-fingerprint?chargePointId=<id>&fingerprint=<hash>
HTTP Response Status
"Certificate fingerprint bound successfully"

Change Security Profile

Updates the target charger's security profile (1, 2, or 3) inside the database to switch how the handshake is validated.

POST /remote/credentials/security-profile?chargePointId=<id>&profile=<1|2|3>
HTTP Response Status
"Security profile updated to 3 successfully"

GetSignedFirmwareUrl

Generates a temporary, HMAC-SHA256 cryptographically signed URL pointing to local server resources to allow secure charger firmware downloading over HTTPS.

GET /remote/firmware/sign-url?chargePointId=<id>&validityMs=3600000
HTTP Response URL
"http://localhost:9779/firmware/download/tn001_cs001_cp001?expires=1783023000000&signature=a9fbc746d..."

BootNotification (WebSocket)

Fires immediately when the Charge Point starts up to initialize registration status with the CSMS.

[
  2,
  "1",
  "BootNotification",
  {
    "reason": "PowerUp",
    "chargingStation": {
      "vendorName": "TechLabs",
      "model": "SmartChargerV2",
      "serialNumber": "TL-99238",
      "firmwareVersion": "2.0.1-v1.4"
    }
  }
]
Field Type Status Description
reason String Required The reason for sending the boot notification. E.g. PowerUp, SystemReset, Triggered.
chargingStation Object Required Object containing physical charger details.
chargingStation.vendorName String Required Name of the charger hardware vendor.
chargingStation.model String Required Model designation of the charger hardware.
chargingStation.serialNumber String Optional Serial number of the physical charger.
chargingStation.firmwareVersion String Optional Firmware version currently loaded on the charger.
chargingStation.chargeBoxSerialNumber String Optional Legacy charge box serial number mapping.
status (Response) String Required CSMS registration decision status: Accepted, Pending, Rejected.
interval (Response) Integer Required Requested heartbeat interval frequency in seconds.
currentTime (Response) String Required CSMS server clock timestamp in ISO 8601 UTC format.

Heartbeat (WebSocket)

Sent periodically by the Charge Point to signal that it is online and running. Also synchronizes server time.

[
  2,
  "2",
  "Heartbeat",
  {}
]
Field Type Status Description
Request Payload is empty ({}).
currentTime (Response) String Required Current server time in ISO 8601 UTC format synchronizing the charger clock.

Authorize (WebSocket)

Authorizes an RFID tag/token value before allowing transaction operations.

[
  2,
  "2",
  "Authorize",
  {
    "idToken": {
      "idToken": "abc",
      "type": "RFID"
    }
  }
]
Field Type Status Description
idToken Object Required Container for identifier token information.
idToken.idToken String Required The authorization identifier tag string (e.g. RFID hexadecimal value).
idToken.type String Required The authorization type. E.g. RFID, Central, Keycode, eMAID.
idTokenInfo (Response) Object Required Container for status information of the identifier.
idTokenInfo.status (Response) String Required Authorization decision status. E.g. Accepted, Blocked, Expired, Invalid.

TransactionEvent (WebSocket)

Controls active session telemetry, energy measurements, and start/stop transaction states.

[
  2,
  "3",
  "TransactionEvent",
  {
    "eventType": "Started",
    "timestamp": "2026-06-24T10:15:00Z",
    "triggerReason": "Authorized",
    "seqNo": 0,
    "transactionInfo": {
      "transactionId": "tx-123",
      "chargingState": "Charging"
    },
    "evse": {
      "id": 1,
      "connectorId": 1
    },
    "idToken": {
      "idToken": "abc",
      "type": "RFID"
    },
    "meterValue": [
      {
        "timestamp": "2026-06-24T10:15:00Z",
        "sampledValue": [
          {
            "value": "100",
            "measurand": "Energy.Active.Import.Register",
            "unit": "Wh"
          }
        ]
      }
    ]
  }
]
Field Type Status Description
eventType String Required The event status type: Started, Updated, or Ended.
timestamp String Required ISO 8601 UTC timestamp of event generation.
triggerReason String Required Trigger reason: Authorized, CableDisconnect, ChargingStateChanged, EnergyLimitReached, RemoteStart, RemoteStop, MeterValuePeriodic.
seqNo Integer Required Incremental sequence number counter for ordering.
transactionInfo Object Required Details about the active transaction.
transactionInfo.transactionId String Required Globally unique identifier string for the active charging session.
transactionInfo.chargingState String Optional Current state of the charging process: Charging, SuspendedEV, SuspendedEVSE, Finishing, Idle.
transactionInfo.stoppedReason String Optional Reason for stopping the transaction: DeAuthorized, EmergencyStop, EVDisconnected, Local, UnlockCommand.
transactionInfo.remoteStartId Integer Optional Remote transaction start request correlation ID.
evse Object Required Physical EVSE outlet parameters.
evse.id Integer Required The unique EVSE index on the charger hardware.
evse.connectorId Integer Optional The specific connector index within the EVSE unit.
idToken Object Optional The authorization credential token initiating/ending the transaction.
meterValue Array of Objects Optional Energy and power telemetry register measurements:
  • timestamp (String): Telemetry reading timestamp.
  • sampledValue (Array): Telemetry values (value, measurand e.g. Energy.Active.Import.Register, unit).

StatusNotification (WebSocket)

Transmits immediate physical availability state updates from the charger's plugs.

[
  2,
  "6",
  "StatusNotification",
  {
    "timestamp": "2026-06-24T10:14:00Z",
    "connectorStatus": "Available",
    "evseId": 1,
    "connectorId": 1
  }
]
Field Type Status Description
timestamp String Required ISO 8601 UTC timestamp of status transition.
connectorStatus String Required Plug occupancy status state: Available, Occupied, Reserved, Unavailable, Faulted.
evseId Integer Required Target EVSE index.
connectorId Integer Required Target connector index within the EVSE.

NotifyEvent (Fault Alerts)

Triggers immediate system fault notifications. Configures error variables in the CSMS databases.

[
  2,
  "7",
  "NotifyEvent",
  {
    "generatedAt": "2026-06-24T10:16:00Z",
    "seqNo": 0,
    "eventData": [
      {
        "eventId": 1,
        "timestamp": "2026-06-24T10:16:00Z",
        "trigger": "AlertOrCondition",
        "actualValue": "Faulted",
        "techCode": "InternalError",
        "techInfo": "Overheating detected",
        "cleared": false,
        "component": {
          "name": "Connector",
          "evse": {
            "id": 1,
            "connectorId": 1
          }
        },
        "variable": {
          "name": "Problem"
        }
      }
    ]
  }
]
Field Type Status Description
generatedAt String Required ISO 8601 UTC timestamp of event report generation.
seqNo Integer Required Incremental sequence counter.
eventData Array of Objects Required List of diagnostic alerts:
  • eventId (Integer): Unique alert ID.
  • timestamp (String): Timestamp when alert changed.
  • trigger (String): Trigger rule type (e.g. AlertOrCondition).
  • actualValue (String): Event parameter value (e.g. "Faulted").
  • cleared (Boolean): True if alert condition has resolved.
  • component (Object): Target physical device block (e.g. name "Connector").
  • variable (Object): Parameter variable measured (e.g. name "Problem").

NotifyReport (WebSocket)

Reports detailed component configuration inventories to the CSMS databases.

[
  2,
  "9",
  "NotifyReport",
  {
    "requestId": 1,
    "generatedAt": "2026-06-24T10:14:00Z",
    "seqNo": 0,
    "reportData": [
      {
        "component": {
          "name": "Connector",
          "evse": {
            "id": 1,
            "connectorId": 1
          }
        },
        "variable": {
          "name": "AvailabilityState"
        },
        "variableAttribute": [
          {
            "value": "Available"
          }
        ]
      }
    ]
  }
]
Field Type Status Description
requestId Integer Required Correlation request reference identifier.
generatedAt String Required ISO 8601 UTC timestamp of configuration snapshot.
seqNo Integer Required Incremental sequence index.
reportData Array of Objects Required Configuration inventory records containing:
  • component (Object): Target logical component.
  • variable (Object): Configuration setting name.
  • variableAttribute (Array): Attributes (e.g. attribute value string).

NotifyMonitoringReport (WebSocket)

Fires to notify the CSMS of active alerts, component variables, and monitoring configuration logs.

[
  2,
  "10",
  "NotifyMonitoringReport",
  {
    "requestId": 1,
    "generatedAt": "2026-06-24T10:14:00Z",
    "seqNo": 0,
    "monitor": [
      {
        "id": "mon-1",
        "severity": "Critical",
        "component": {
          "name": "Connector",
          "instance": "plug-1",
          "evse": {
            "id": 1,
            "connectorId": 1
          }
        },
        "variable": {
          "name": "Problem",
          "instance": "temp-sensor"
        }
      }
    ]
  }
]
Field Type Status Description
requestId Integer Required Correlation monitor request reference ID.
generatedAt String Required ISO 8601 UTC report generation timestamp.
seqNo Integer Required Incremental sequence number counter.
monitor Array of Objects Required Monitored logic parameters:
  • id (String): Unique monitor threshold rule ID.
  • severity (String): Severity level: Critical, Error, Warning.
  • component (Object): Target physical device component block.
  • variable (Object): Monitored sensor variable parameter.

SecurityEventNotification (WebSocket)

Sent by the Charge Point to report physical tampering, diagnostic warnings, or internal security alarms.

[
  2,
  "11",
  "SecurityEventNotification",
  {
    "type": "TamperDetection",
    "timestamp": "2026-07-03T11:00:00Z",
    "techInfo": "Cabinet door opened"
  }
]

SignCertificate (WebSocket)

Sent by the Charge Point to request certificate signing (CSR validation) from the Central System CA.

[
  2,
  "12",
  "SignCertificate",
  {
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMOCK_CSR_DATA\n-----END CERTIFICATE REQUEST-----"
  }
]

LogStatusNotification (WebSocket)

Sent by the Charge Point to update the CSMS on the diagnostic or security logs upload progress.

[
  2,
  "13",
  "LogStatusNotification",
  {
    "status": "Uploaded",
    "requestId": 12
  }
]

SignedUpdateFirmware (WebSocket)

Sent remotely by the CSMS to trigger a cryptographically signed firmware download and install sequence on the charger.

[
  2,
  "14",
  "SignedUpdateFirmware",
  {
    "requestId": 101,
    "firmware": {
      "location": "https://localhost:9779/firmware/download/tn001_cs001_cp001?expires=...",
      "retrieveDateTime": "2026-07-03T12:00:00Z",
      "signingCertificate": "-----BEGIN CERTIFICATE-----\n...",
      "signature": "304502210086..."
    }
  }
]

SignedFirmwareStatusNotification (WebSocket)

Sent by the Charge Point to update the CSMS on the installation status of a signed firmware binary.

[
  2,
  "15",
  "SignedFirmwareStatusNotification",
  {
    "status": "Installed",
    "requestId": 101
  }
]