OCPP 2.0.1 CSMS Server API
Complete developer guide and payload reference for the OCPP 2.0.1 Central Services Management System (CSMS).
| 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 |
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 a400 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:
[ <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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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:
|
GetLocalListVersion
Requests the current version number of the local authorization list from the Charge Point.
{
"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>[
{
"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>"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>"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>"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>"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://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. |
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:
|
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:
|
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:
|
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:
|
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
}
]