POST /vendors/{id}/connections with type: "ocpp" → read flowOptions[name="ocppUrl"] from the response → display the wss:// URL to the user → user enters it in their wallbox config
The ocppUrl from flowOptions is stable from the moment the connection is created — safe to display, print, or store immediately. Do not use the URL from GET /connection-options; it is a randomized preview
The wallbox won't show up in GET /vendors/{id}/devices until it actually connects to the OCPP endpoint — tell users to save & restart
Only one pending connection allowed — if you need a new one, DELETE the old connection first (devices must be unlinked first)
Complete flow for connecting OCPP wallboxes via the Connect API.
Notes
Vendor/Model is a 1 to 1 relation (one Vendor per Model)
Only one pending connection at a time (this constraint might be removed in future)
OCPP-HOME-ID: unique OCPP identifier per home/user, automatically created by the Connect API
DEVICE-TAG: Some devices require this id, but it's optional for others. In case the device requires the ID, it will be added by the Connect API. If not required, this part of the URL will not be provided
Warning — do not display this URL to the user. The DEVICE-TAG segment in this pre-creation response is freshly randomized on every read and is never persisted. Use this endpoint only to discover the flow type and field layout. The URL to give to the user is the one returned as flowOptions[name="ocppUrl"] after you create the connection in Step 3 — that one is stable.
Step 3: Create Connection
Code
POST /v1/users/{userId}/vendors/{vendorId}/connections
Note: Read the URL from flowOptions[name="ocppUrl"].data. Match by name, not by index — order is not guaranteed. The device tag in the URL is minted and persisted when the connection is created, so the URL is stable from this point on. The same array (with the identical URL) is re-surfaced on every GET /v1/users/{userId}/vendors/connections?vendorId=... call, so you can recover the URL later without re-creating the connection.
Step 4: User Interaction required: Enter OCPP URL in Wallbox
Ask the wallbox owner to:
Open the configuration interface of their wallbox (web UI or app).
Locate the setting for the OCPP server URL (sometimes called backend URL or charge point management URL).
Use the ocppUrl value from the flowOptions array returned in Step 3: Create Connection (or re-fetched via GET /v1/users/{userId}/vendors/connections?vendorId={vendorId}) in the wallbox device.
Save/apply the configuration and, if required by the device, restart the wallbox.
URL stability: The device tag is generated and persisted when the connection is created, so the flowOptions URL is stable from creation onward. Once the wallbox has booted, its persisted device tag continues to be used — the URL never changes between reads.
Order doesn't break onboarding: If the wallbox was already configured with an OCPP URL before the connection was created (e.g. from an earlier attempt), creating the connection triggers a server-side re-match of already-connected wallboxes. In that case the device typically appears in GET /devices within ~10 seconds without restarting the wallbox.
As soon as the wallbox connects to the OCPP endpoint, it will appear in Step 6: List Devices from Vendor.
Step 5: Delete Connection (Optional)
In case the connection is not established, the connection should be deleted as there may only be one connection with unassigned OCPP devices at a time per userId.
Important: All devices attached to the connection must be deleted first (via DELETE /v1/users/{userId}/devices/{deviceId}). If you attempt to delete a connection with linked devices, the endpoint will return an error.
Step 6: List Devices from Vendor
Code
GET /v1/users/{userId}/vendors/{vendorId}/devices?connectionId=2c659624-ea66-49db-ae98-716b2e73fb0d
