Documentation

Connect UI

Copy page

BETA

The Connect UI flow lets a user connect a vendor account without your application handling vendor-specific login. You create a session, send the browser to the returned URL, and get the user back once they're done. Everything in between is handled by clever-PV.

OCPP wallboxes and push meters still use the dedicated OCPP and push onboarding pages. Branding of the hosted pages is not configurable yet.

To implement vendor login yourself instead, see Device Onboarding Flow.

1. Create a session

Code
POST /v1/users/{userId}/connections/sessions
Authorization: Bearer <user access token>

Code
{
  "vendorId": "e6a1...-guid",
  "redirectUri": "https://your-app.example.com/callback",
  "popup": false,
  "language": "de"
}

Response 200 OK:

Code
{
  "sessionId": "5f2c...",
  "connectUrl": "https://connect.clever-pv.com/{vendorId}/connect?sessionId=5f2c...&lang=de"
}

Field	Required	Notes
vendorId	yes	Vendor from GET /v1/users/{userId}/vendors.
redirectUri	yes	Where the browser returns on success. Register allowed URIs via the clever-PV Partner Portal. If redirectUri already has a query string, connectionId is appended with &.
popup	no	Default false: full-page redirect back to redirectUri. true: Connect UI closes itself and notifies the opener via postMessage — see Popup mode.
language	no	Supported languages: de, en, nl, fr, it, es, pt, el, fi, sv, hr, sk, sl, et, lv, lt, bg.

• Auth: the current user's access token — a session is always tied to that user's home.
• 404 if the user has no home.
• To repair/re-authorize an existing connection, use POST /v1/users/{userId}/connections/{connectionId}/sessions with the same body.

A session is single-use and expires after a few minutes. Create a fresh one each time you start the flow.

2. Redirect the browser

Send the user's browser to connectUrl. Connect UI runs the vendor login and creates the connection. You do not implement vendor-specific screens.

3. Handle the return

Redirect mode (popup: false, default)

On success the browser is sent to your redirectUri with the new connection id:

Code
https://your-app.example.com/callback?connectionId=8f1a...

On failure the user stays on Connect UI. There is no error redirect to your redirectUri and no connectionId. Show a way to retry (create a new session) when the user comes back without one.

Popup mode

Set popup: true and open connectUrl with window.open so Connect UI can reach window.opener. On success it posts { "status": "connected" } to the origin of your redirectUri and closes the window. The message does not include connectionId — list the user's connections (GET /v1/users/{userId}/vendors/connections) and take the new id.

Code
const connectOrigin = new URL(connectUrl).origin; // e.g. https://connect.clever-pv.com
const popup = window.open(connectUrl, "clever-pv-connect", "popup");

window.addEventListener("message", (event) => {
  if (event.origin !== connectOrigin) return;
  if (event.data?.status !== "connected") return;
  // poll GET .../vendors/connections for the new connectionId
});

Verify event.origin against the Connect UI host (connectUrl's origin), not against your own app origin. Failures stay on the Connect UI error page; the popup is not closed for you.

Failure pages

Connect UI shows a localized error page. The code in the path is:

code	When
session_expired	Session unknown, already used, or timed out. Create a new session.
user_denied	The user refused to authorize the connection.
cookie_missing	A required cookie was blocked — common in in-app browsers. Ask the user to open the link in the device's default browser.
provider_error	The vendor login failed. Retry with a new session.
partner_not_configured	No usable redirectUri on the session. Check the URI you sent.
credentials_invalid	The user can correct the input and try again on the same page. This is not a terminal error page.

Unknown codes render as 404 on Connect UI and are not a partner callback.

Requirements

Register your client's allowed redirect URIs via the clever-PV Partner Portal before the first session. Multiple URIs are supported; an empty list means the connect flow is not available for that client yet.

After a successful return, continue with listing vendor devices and linking a device — Connect UI only creates the connection, not the clever-PV device.

Example flow