Documentation

Copy page

Connect API - Device Onboarding

TL;DR

• GET /vendors → GET /vendors/{id}/connection-options → run the OAuth/form flow → POST /vendors/{id}/connections → GET /vendors/{id}/devices → POST /devices
• The flow field tells you which auth to implement: oidcProxy (WebView + intercept redirect), oidc (PKCE + deep link), ocpp (user pastes URL in wallbox), push (user pastes URL in vendor portal), form (text/secret fields). flow is returned per vendor on GET /vendors and again on GET /connection-options — call connection-options for the form/login details, not just to learn the flow type
• GET /vendors/{id}/devices returns VendorDevices — link candidates read live from the vendor, no clever-PV id. Already linked devices can still appear with available: false. They are not the same thing as the Devices returned by GET /devices after linking. See Concept: VendorDevice vs. Device
• After POST /devices (linking), the device appears in GET /devices with its capabilities[] — that's where real interaction starts

Complete flow for connecting vendor devices via the Connect API.

Just browsing the catalog? The vendor/model catalog is also reachable without authentication via the Public Vendor Catalog — authenticate to get your app-scoped catalog, or call anonymously for the default clever-PV catalog. Onboarding itself still requires the authenticated flow below.

Don't want to implement vendor login yourself? Hand the browser to Connect UI instead of steps 2–4, then list vendor devices and link them. OCPP wallboxes and push meters stay on the dedicated pages below.

---

Step 1: List Vendors

Code
GET /v1/users/{userId}/vendors

Response:

Code
{
  "data": [
    { "id": "ce1332aa-5d51-4222-8b4a-f759862b3ced", "name": "Home Connect", "flow": "oidcProxy" },
    { "id": "c36018d3-334e-4d44-82b9-324f2ff7de41", "name": "Solvis", "flow": "form" },
    { "id": "ae1b4468-217e-440d-a2c7-3c44d283a6c1", "name": "Tesla", "flow": "oidcProxy" },
    { "id": "09527b83-6665-4202-9666-a59840ef3a27", "name": "Vaillant", "flow": "form" },
    { "id": "e591b6fb-9fdc-4283-ade9-d16266572882", "name": "Viessmann", "flow": "oidc" },
    { "id": "32630d0a-467b-4f8f-8dd0-b417e78a0b70", "name": "Volkswagen", "flow": "oidcProxy" },
    { "id": "4c8e9a1b-3d2f-4e5c-8a7d-1b2c3d4e5f6a", "name": "go-e V3/Gemini/Pro via OCPP", "flow": "ocpp" },
    { "id": "8f2e1d5c-9b4a-4c3e-b2a1-7f6e5d4c3b2a", "name": "Generic Push", "flow": "push" }
  ]
}

Note: flow is a non-nullable string per vendor. Values: form | oidcProxy | oidc | ocpp | push. The vendor → flow mapping is not contractual — re-read it on every onboarding attempt.

---

Step 2: Get Connection Options

Code
GET /v1/users/{userId}/vendors/{vendorId}/connection-options

Response Structure:

Code
{
  flow: "form" | "oidcProxy" | "oidc" | "ocpp" | "push",
  formOptions: Array<{
    type: "text" | "secret" | "login",
    data: Record<string, any>
  }>,
  docUrl: string | null
}

Note: Enum values are serialized as camelCase strings.

---

When to use which flow

You don't choose the flow — the vendor does. You receive it on GET /vendors (per vendor) and again on GET /connection-options. Your job is to implement the five flow types so your client can handle whichever vendor the user picks.

Flow	Used by (typical)	What the client must implement	Why this flow
oidcProxy	Tesla, Volkswagen, Home Connect	A WebView that opens data.url, intercepts the redirect URL containing data.redirect, and POSTs the full URL back. No token handling on the client.	Vendor requires a confidential OAuth client; clever-PV holds the secret and exchanges the code server-side.
oidc	Viessmann	Standard OIDC with PKCE: generate code_verifier/code_challenge, register the deep-link com.cleverpv.cleverpv://oauthredirect/, exchange code yourself.	Vendor allows a public OAuth client; PKCE keeps it secure without a server secret.
ocpp	Wallboxes (any OCPP-1.6/2.0.1 hardware)	Display a generated OCPP server URL to the user; they paste it into the wallbox's own configuration UI. No browser flow.	OCPP is a wallbox-to-backend protocol — the wallbox itself initiates the connection.
push	Push-based electric meters	After POST /connections, read flowOptions[name="pushUrl"] from the response and display it to the user; they paste it into their vendor portal. No browser flow, no client secret. See the dedicated Push Meter Onboarding page.	Vendor-initiated server-push — the vendor portal posts telemetry to the URL on its own cadence; no client secret leaves the server.
form	Shelly, Vaillant (and others without OAuth)	Render the returned formOptions (text/secret fields or a vendor consent WebView) and POST the collected values as data.	Vendor has no OAuth at all — either a static API key/serial number, or a vendor-specific consent page that returns parameters in the redirect URL.

Decision rules for client code:

1. Always branch on flow. Never assume a vendor uses a specific flow — vendors can change, and new vendors can be added at any time without a Connect-API version bump.
2. oidcProxy and oidc look similar but are NOT interchangeable. oidcProxy requires forwarding the full redirect URL; oidc requires you to extract the code yourself and send it together with the original code_verifier.
3. ocpp has no user-facing browser step. If you build an in-app onboarding wizard, the ocpp branch must show instructions and the OCPP URL — not a WebView.
4. push also has no browser step. The URL is not in formOptions — it is returned in the flowOptions array of the create-connection response (see Step 4). Display the URL, instruct the user to paste it into the vendor portal.
5. For form, inspect formOptions[].type before rendering: text and secret are simple inputs, login is a WebView whose intercepted redirect URL you forward unchanged as data.url (see Option D below).

The vendor IDs returned by GET /vendors are stable, but vendor → flow mapping is not contractual. Always re-fetch /connection-options per onboarding attempt.

---

Step 3: OAuth Flow

Based on the flow value, execute the appropriate OAuth flow:

Flow Types:

• oidcProxy: OAuth flow proxied through Clever PV servers. User authenticates via vendor's OAuth page, Clever PV handles token exchange.
• oidc: Direct OpenID Connect flow.
• ocpp: Open Charge Point Protocol flow for wallboxes. User manually enters OCPP server URL in their device configuration.
• push: Vendor-initiated server-push for electric meters. User manually enters a generated push URL in the vendor portal. URL + API key are returned in the create-connection response (flowOptions).
• form: Non-OAuth authentication using vendor-specific forms (text fields, secrets) or vendor consent pages.

Option A: "oidcProxy"

Example Response from Get Connection Options (here: Tesla):

Code
{
  "flow": "oidcProxy",
  "formOptions": [
    {
      "type": "login",
      "data": {
        "url": "https://fleet-auth.prd.vn.cloud.tesla.com/oauth2/v3/authorize?client_id=da4d8a7f845c-4df5-929b-94d3fb60d002&locale={{ locale }}&prompt=login&redirect_uri=https%3A%2F%2Fapp.clever-pv.com%2Foauth2%2Ftesla&response_type=code&scope=openid%20vehicle_device_data%20offline_access%20vehicle_cmds%20vehicle_charging_cmds%20vehicle_location&require_requested_scopes=true&prompt_missing_scopes=true",
        "redirect": "oauth2/tesla"
      }
    }
  ],
  "docUrl": "https://hemssupport.zendesk.com/hc/de/articles/23043735141394-Tesla-Auto"
}

Flow:

1. Open data.url in WebView (replace {{ locale }} with e.g. de)
2. User authenticates with vendor
3. Detect and intercept redirection in WebView: URL contains data.redirect string
4. Store the intercepted URL (including the code) in memory for usage in the "Create Connection" step

Redirect Detection:

Code
webview.onUrlChange = (url) => {
  if (url.includes(flowData.redirect)) {  // e.g. "oauth2/tesla"
    const code = new URL(url).searchParams.get('code');
    closeWebView();
    createConnection(code);
  }
};

Example Redirect URL:

Code
https://app.clever-pv.com/oauth2/tesla?locale=de-DE&code=EU_7e23957a43ca73afa71ecac056d8c869b8ddd548386bd2e98682e6e5df02&issuer=https%3A%2F%2Ffleet-auth.tesla.com%2Foauth2%2Fv3

---

Option B: "oidc" (Direct OIDC with PKCE)

For this flow you have to register the redirect Url com.cleverpv.cleverpv://oauthredirect/ as a deep link handler.

Notice: The redirectUrl is predefined by Clever PV and cannot be customized. You must use the redirect URL returned by the API (com.cleverpv.cleverpv://oauthredirect/) this might lead to conflicting deep link handling, when the user also has the clever-PV app installed on the same device.

Example Response (here: Viessmann):

Code
{
  "flow": "oidc",
  "formOptions": [
    {
      "type": "login",
      "data": {
        "clientId": "e995fcd7eb8205369bf35cba4c3ab9f1",
        "redirectUrl": "com.cleverpv.cleverpv://oauthredirect/",
        "discoveryUrl": "https://iam.viessmann-climatesolutions.com/.well-known/openid-configuration",
        "scopes": ["IoT", "User", "offline_access"],
        "grantType": "authorization_code"
      }
    }
  ],
  "docUrl": null
}

Flow:

1. Fetch OIDC config from discoveryUrl
2. Generate PKCE: code_verifier (random 64 chars) → code_challenge (SHA256 + Base64URL)
3. Build authorization URL with code_challenge
4. Register deep link handler for redirectUrl scheme
5. User authenticates, app receives deep link with code

PKCE Generation:

Code
const code_verifier = generateRandomString(64);
const code_challenge = base64UrlEncode(sha256(code_verifier));

Authorization URL:

Code
https://iam.viessmann-climatesolutions.com/idp/v3/authorize
  ?client_id=e995fcd7eb8205369bf35cba4c3ab9f1
  &redirect_uri=com.cleverpv.cleverpv://oauthredirect/
  &response_type=code
  &scope=IoT User offline_access
  &code_challenge={code_challenge}
  &code_challenge_method=S256
  &state={random_state}

Redirect Detection:

Code
app.onDeepLink = (url) => {
  if (url.startsWith(flowData.redirectUrl)) {
    const code = new URL(url).searchParams.get('code');
    createConnection(code, storedCodeVerifier);
  }
};

---

Option C: "ocpp" (OCPP Wallbox Protocol)

For OCPP-enabled wallboxes, the API provides a unique OCPP server URL that the user must manually configure in their wallbox device.

Example Response:

Code
{
  "flow": "ocpp",
  "formOptions": [
    {
      "type": "text",
      "data": {
        "value": "wss://ocpp.clever-pv.com/<OCPP-HOME-ID>/<DEVICE-TAG>",
        "readonly": true,
        "label": "OCPP Connection URL",
        "description": "Enter this URL in your wallbox configuration"
      }
    }
  ],
  "docUrl": null
}

Flow:

1. Create the connection first: POST /vendors/{vendorId}/connections with type: "ocpp"
2. Read the stable URL from flowOptions[name="ocppUrl"] in the create response
3. Display that URL to the user and instruct them to open their wallbox's configuration interface
4. User enters the OCPP URL in the wallbox settings, saves and restarts the wallbox (if required)
5. Wallbox connects to Clever PV's OCPP endpoint
6. Device becomes available in "List Devices of Connection" step

Note: The URL shown by GET /connection-options (example above) is a randomized preview — its device tag changes on every read. Always use the flowOptions[name="ocppUrl"] URL from the connection, which is stable from creation onward (also re-surfaced on GET /vendors/connections).

Note: The wallbox will not appear in the devices list until it successfully connects to the OCPP endpoint for the first time.

---

Option D: "form" (Vendor-Specific Forms)

For vendors without OAuth, the API returns form fields to collect. Field types:

• "text": Simple text input (e.g., serial number)
• "secret": Password input (masked, e.g., API key)
• "login": WebView-based consent flow (not OAuth)

Example Response (Text Field):

Code
{
  "flow": "form",
  "formOptions": [
    {
      "type": "text",
      "data": {
        "name": "serialNumber",
        "label": "Seriennummer"
      }
    }
  ],
  "docUrl": "https://www.clever-pv.com/anleitungen/vaillant"
}

Text Field Flow:

1. Display input field for data.label
2. User enters value
3. POST with collected data as shown in the Create Connection - For "form" sub-section.

Example Response (Login Field):

Code
{
  "flow": "form",
  "formOptions": [
    {
      "type": "login",
      "data": {
        "url": "https://devices.acmecorp.com/en/invite?companyId=00000000-0000-0000-0000-000000000000&redirectUri=https%3A%2F%2Fapp.clever-pv.com%2Fverify%2Facme&state={state}",
        "redirect": "verify/acme"
      }
    }
  ],
  "docUrl": null
}

Login Field Workflow:

The "login" field resembles a redirect-based flow similar to OAuth, but it's not standard OIDC/OAuth2. Instead, it's a vendor-specific flow. When a login field is present, it's always the only field in the array.

1. Replace placeholders in data.url (see below), then open it in a WebView (vendor's consent/login page)
2. User authenticates or grants consent on vendor's page
3. Vendor redirects to URL containing data.redirect string
4. Intercept the redirect and forward the complete redirect URL, unchanged (including its query string), as data.url in the POST request with type: "form" — the same pattern as the oidcProxy flow. The Connect API parses the vendor-specific query parameters server-side.

Important: This is not OAuth2/OIDC - there's no authorization code exchange, no tokens. The redirect URL simply contains vendor-specific parameters (like gateway IDs, consent status). Do not parse them out and send them as individual fields — send the full URL as data.url, otherwise the request fails with 401 invalidCredentials.

Placeholders in data.url: The login URL may contain {state} — a blank the server intentionally does not fill in. Filling it is your job before you open the URL in the WebView. Any random string works: the Connect API never looks at the value. Its only purpose is that the vendor attaches the same value to the redirect URL again, so you can check that the callback really belongs to the login you started. Don't confuse it with {{ locale }} (see Option A): double braces are the server's own placeholder system, which normally arrives already resolved — locale is the only one the client replaces there too.

Example:

Code
// 1. Replace placeholders, then open vendor's consent/login page
const loginUrl = field.data.url.replace('{state}', generateRandomString(32));
webview.open(loginUrl);

// 2. Detect redirect (vendor redirects after user action)
webview.onUrlChange = (url) => {
  if (url.includes(field.data.redirect)) {
    closeWebView();

    // 3. Send the full redirect URL, unchanged, to the Connect API with type: "form"
    fetch(`/v1/users/{userId}/vendors/{vendorId}/connections`, {
      method: 'POST',
      body: JSON.stringify({
        type: "form",
        data: { url: url }
      })
    });
  }
};

---

Option E: "push" (Push API for Electric Meters)

For push-based electric meters, the API generates a unique push URL on connection creation — not in the connection-options response. The user pastes that URL into their vendor portal so the vendor can post telemetry to Clever PV.

Example Response (from GET /connection-options):

Code
{
  "flow": "push",
  "formOptions": [],
  "docUrl": "https://hemssupport.zendesk.com/hc/de/articles/22299049097234-Push-API"
}

Note: formOptions is intentionally empty — the URL is minted by POST /connections (see Step 4: For "push") and returned inside flowOptions.

Flow:

1. Call POST /connections with { "type": "push" }
2. Read flowOptions[name="pushUrl"].data from the response and display it
3. Instruct the user to open their vendor portal and paste the URL into the push/webhook URL field
4. User saves the configuration
5. Vendor starts posting telemetry at its own cadence
6. Device becomes available immediately in Step 7 — you do not need to wait for the first push

See also: Push Meter Onboarding for a complete step-by-step walkthrough with real example payloads.

---

Step 4: Create Connection

Heads-up — two unrelated type fields: The type discriminator in the request body below must be one of form, oidcProxy, oidc, ocpp, push (the onboarding flows from DeviceOnboardingFlow).
The type you may have seen inside formOptions[] (e.g. text, secret, login) is a form-field type and is unrelated to the connection request — never use it as the request type.

Heads-up — flowOptions on the response: Some flows return a generic flowOptions array on the connection response — a list of {name, data} pairs surfacing flow-specific values the client needs after the connection exists. Today push populates it (with pushUrl and apiKey) and ocpp populates it (with ocppUrl). Match entries by name; order is not guaranteed.

For "oidcProxy":

Code
POST /v1/users/{userId}/vendors/{vendorId}/connections

{
  "type": "oidcProxy",
  "data": {
    "url": "https://app.clever-pv.com/oauth2/tesla?locale=de-DE&code=<AUTH-CODE>&issuer=https%3A%2F%2Ffleet-auth.tesla.com%2Foauth2%2Fv3"
  }
}

For "oidc":

Code
POST /v1/users/{userId}/vendors/{vendorId}/connections

{
  "type": "oidc",
  "data": {
    "code": "AUTH_CODE_123",
    "codeChallenge": "original_code_verifier"
  }
}

Note: Field is named codeChallenge but expects the code_verifier value.

For "ocpp":

Code
POST /v1/users/{userId}/vendors/{vendorId}/connections

{
  "type": "ocpp",
  "data": {}
}

Response:

Code
{
  "connectionId": "2c659624-ea66-49db-ae98-716b2e73fb0d",
  "vendorId": "<vendorId>",
  "flowOptions": [
    {
      "name": "ocppUrl",
      "data": "wss://ocpp.clever-pv.com/<OCPP-HOME-ID>/<DEVICE-TAG>"
    }
  ]
}

Note: Read flowOptions[name="ocppUrl"] from this response (or re-fetched via GET /vendors/connections) — don't compose the URL from connection-options yourself. Only one pending OCPP connection is allowed at a time per user. If the wallbox doesn't connect, delete the connection before creating a new one.

For "push":

Code
POST /v1/users/{userId}/vendors/{vendorId}/connections

{
  "type": "push"
}

Response:

Code
{
  "connectionId": "<CONNECTION_ID>",
  "vendorId": "e4f7a2b5-d8c1-4a4f-b7a2-5e8c1d4f7a2b",
  "flowOptions": [
    {
      "name": "pushUrl",
      "data": "https://push.clever-pv.com/api/v2/<HOME_ID>/generic-push/<CONNECTION_ID>?code=<API_KEY>"
    },
    {
      "name": "apiKey",
      "data": "<API_KEY>"
    }
  ]
}

Note: The push flow needs no data payload — the connection itself mints the credential. Read pushUrl and apiKey from the flowOptions array (match by name, not by index). Multiple open push connections per vendor are allowed.

For "form":

Code
POST /v1/users/{userId}/vendors/{vendorId}/connections

{
  "type": "form",
  "data": {
    "serialNumber": "1234567890"
  }
}

Or, for a login field, with the full intercepted redirect URL (do not send parsed query parameters as individual fields):

Code
POST /v1/users/{userId}/vendors/{vendorId}/connections

{
  "type": "form",
  "data": {
    "url": "https://app.clever-pv.com/verify/acme?gatewayId=abc123&contractStatus=accepted&state=xyz789"
  }
}

Response:

Code
{
  "connectionId": "4d42038f-0da4-4b07-b6bb-f48e6c54cd3e",
  "vendorId": "ae1b4468-217e-440d-a2c7-3c44d283a6c1"
}

---

Step 5: Delete Connection (Optional)

Currently only supported for specific flow. Support for missing flows will be implemented soon.

For OCPP, this is mandatory cleanup when a wallbox fails to connect — only one pending OCPP connection is allowed per user. For Push, deletion is purely optional; multiple open push connections are allowed, so you only need to delete to revoke an API key.

Code
DELETE /v1/users/{userId}/vendors/{vendorId}/connections/{connectionId}

Response: 204 No Content on success

Important: All devices attached to the connection must be deleted first (via DELETE /v1/users/{userId}/devices/{deviceId} — see Step 10: Delete Device). If you attempt to delete a connection with linked devices, the endpoint will return an error.

Use cases:

• Wallbox failed to connect to the OCPP endpoint
• User entered incorrect configuration
• Need to create a new OCPP connection (must delete the existing one first)

---

Step 6: List User Connections (Optional)

Code
GET /v1/users/{userId}/vendors/connections?vendorId={vendorId}
Authorization: Bearer {jwt}

Response:

Code
{
  "data": [
    {
      "connectionId": "4d42038f-0da4-4b07-b6bb-f48e6c54cd3e",
      "vendorId": "ae1b4468-217e-440d-a2c7-3c44d283a6c1"
    },
    {
      "connectionId": "<CONNECTION_ID>",
      "vendorId": "e4f7a2b5-d8c1-4a4f-b7a2-5e8c1d4f7a2b",
      "flowOptions": [
        {
          "name": "pushUrl",
          "data": "https://push.clever-pv.com/api/v2/<HOME_ID>/generic-push/<CONNECTION_ID>?code=<API_KEY>"
        },
        {
          "name": "apiKey",
          "data": "<API_KEY>"
        }
      ]
    },
    {
      "connectionId": "2c659624-ea66-49db-ae98-716b2e73fb0d",
      "vendorId": "4c8e9a1b-3d2f-4e5c-8a7d-1b2c3d4e5f6a",
      "flowOptions": [
        {
          "name": "ocppUrl",
          "data": "wss://ocpp.clever-pv.com/<OCPP-HOME-ID>/<DEVICE-TAG>"
        }
      ]
    }
  ]
}

Note: flowOptions is re-surfaced on every list call for flows that need it. Today push populates it (pushUrl, apiKey) and ocpp populates it (ocppUrl); for other connections the field is null / omitted. Match items by name, not by index — order is not guaranteed.

---

Concept: VendorDevice vs. Device

Step 7 and Step 9 below both return something you might call "a device" — they are not the same resource, and conflating them is the most common source of confusion in this flow.

	VendorDevice (Step 7)	Device (Step 8 / 9)
Returned by	GET /vendors/{vendorId}/devices?connectionId=	POST /devices, GET /devices, GET /devices/{deviceId}
Identity	No clever-PV id. Identified by externalId (the vendor's own serial number / VIN / gateway id) + the connectionId it was found under	Stable clever-PV id (GUID) — used for every further call (PATCH, PUT /{capability}, DELETE)
Where it comes from	Fetched live from the vendor's own API on every call — not stored by clever-PV. Already linked devices can still appear with available: false	A persisted clever-PV resource, created exactly once via POST /devices
What it's for	A candidate to show the user so they can pick what to link	The linked, functional device — the only place capabilities[] (telemetry, control, interventions) exist

Linking one to the other: POST /devices (Step 8) takes the VendorDevice's externalId, its model.id, and the connectionId — that's the entire bridge between the two objects. name/text on the VendorDevice are display suggestions only; they are not copied over automatically, so pass them again in the POST /devices body if you want the same label to stick.

What available: false actually means

The API collapses several distinct situations into a single boolean:

• a Device already exists for this externalId — in the current home, or in a different home (the same vendor account, and therefore the same externalId, can be visible to more than one clever-PV home)
• the vendor itself reports the device as offline, on unsupported firmware, or an unsupported model

Note: The response only exposes available, not the reason behind it — you cannot tell "already linked by you", "already linked under a different home", and "vendor says it's unusable" apart from the VendorDevice alone.

Important: externalId uniqueness is checked globally across all homes when you call POST /devices, not just within the current home. If a Device already exists for that externalId, the request returns 409 Conflict with errorCode: DUPLICATE_DEVICE, including if it was linked between your GET and your POST. This error describes a duplicate, not every cause of available: false.

Firmware and model compatibility

Devices whose models are available for selection in your app's catalog can still be returned with available: false if the vendor reports incompatible firmware or an unsupported model. Devices whose models are missing from that catalog or cannot be selected are omitted; Step 7 returns 206 Partial Content when such models are found, with only the supported catalog entries in data.

The response does not expose a status, a detailed compatibility reason, or a required firmware version. Do not infer a particular reason from available: false; keep the device unavailable for selection and show a general availability message.

---

Step 7: List Devices of a Connection

Code
GET /v1/users/{userId}/vendors/{vendorId}/devices?connectionId={connectionId}

Response:

Code
{
  "data": [
    {
      "name": "Test Tesla",
      "text": "<VIN of Test Tesla>",
      "model": {
        "id": "1ffc08b8-0319-4790-a7d9-0aa5a56fe34d",
        "name": "Model Y",
        "category": "car"
      },
      "externalId": "<VIN of Test Tesla>",
      "available": true,
      "connectionId": "4d42038f-0da4-4b07-b6bb-f48e6c54cd3e"
    }
  ]
}

---

Step 8: Link Device

Only offer devices with available: true from Step 7 for linking. Availability can change between listing and linking, so a successful list response does not guarantee that the following request will succeed.

Code
POST /v1/users/{userId}/devices
Content-Type: application/json

{
  "name": "Test Tesla",
  "externalId": "<VIN of Test Tesla>",
  "modelId": "1ffc08b8-0319-4790-a7d9-0aa5a56fe34d",
  "connectionId": "4d42038f-0da4-4b07-b6bb-f48e6c54cd3e"
}

Response Similar to result of step "Get Linked Devices"

If linking fails, inspect the HTTP status and error response, including errorCode, and refresh the device list before offering another attempt. Only offer devices that are still listed with available: true, and address the reported error before retrying. 409 Conflict with DUPLICATE_DEVICE means the device is already linked. Other failures can involve authentication or vendor communication; they do not by themselves identify firmware or model incompatibility. There is no single HTTP status for every cause of available: false.

---

Step 9: Get Linked Devices

Code
GET /v1/users/{userId}/devices

Note: For push-style devices, the connect capability's data carries a flowOptions array mirroring the connection-level flowOptions (pushUrl, apiKey). OCPP devices behave the same way — their connect capability surfaces ocppUrl so you can recover the WebSocket URL from the device alone without re-fetching the connection. See Push Meter Onboarding → Step 7 for the push shape.

Response:

Code
{
  "data": [
    {
      "id": "0f43fcf9-62cc-4bab-88b0-b0a4c12bf4b6",
      "name": "Test Tesla",
      "externalId": "<VIN of Test Tesla>",
      "model": {
        "id": "1ffc08b8-0319-4790-a7d9-0aa5a56fe34d",
        "name": "Model Y",
        "category": "car",
        "vendor": {
          "id": "ae1b4468-217e-440d-a2c7-3c44d283a6c1",
          "name": "Tesla"
        }
      },
      "capabilities": [
        {
          "name": "location-detection",
          "data": { "latitude": 11.1111111, "longitude": 22.2222222 },
          "options": null,
          "interventions": []
        },
        {
          "name": "on-off",
          "data": { "state": "on" },
          "options": null,
          "interventions": []
        },
        {
          "name": "display-power",
          "data": { "power": 10700, "lastUpdate": null },
          "options": null,
          "interventions": []
        },
        {
          "name": "display-charging-state",
          "data": { "chargingState": "charging" },
          "options": {
            "chargingState": ["noCarConnected", "charging", "waitingOnCar", "completed", "error", "awaitingStart", "waitingForStatus"]
          },
          "interventions": []
        },
        {
          "name": "solar-optimization",
          "data": { "enabled": false, "ratedCapacity": 4140, "sunShare": 100 },
          "options": null,
          "interventions": []
        },
        {
          "name": "display-soc",
          "data": { "soc": 56, "lastUpdate": null },
          "options": null,
          "interventions": []
        },
        {
          "name": "core",
          "data": { "name": "Test Tesla", "connectivityStatus": "online" },
          "options": null,
          "interventions": []
        },
        {
          "name": "min-max-amperage",
          "data": { "minAmperage": 6, "maxAmperage": 16 },
          "options": { "absoluteMinAmperage": 6, "absoluteMaxAmperage": 16 },
          "interventions": []
        },
        {
          "name": "set-charge-limit",
          "data": { "chargeLimit": 100 },
          "options": { "minChargeLimit": 0, "maxChargeLimit": 100 },
          "interventions": []
        },
        {
          "name": "set-charging-power",
          "data": { "desiredAmperage": 5 },
          "options": { "minAmperage": 6, "maxAmperage": 16 },
          "interventions": []
        },
        {
          "name": "display-charging-phases",
          "data": { "phases": 3 },
          "options": null,
          "interventions": []
        },
        {
          "name": "phase-mode",
          "data": { "phaseMode": "threePhases" },
          "options": { "availablePhaseModes": ["singlePhase", "twoPhases", "threePhases"] },
          "interventions": []
        },
        {
          "name": "display-charging-current",
          "data": { "amperage": 16 },
          "options": null,
          "interventions": []
        },
        {
          "name": "rated-capacity",
          "data": { "ratedCapacity": 4140 },
          "options": null,
          "interventions": []
        },
        {
          "name": "display-estimated-range",
          "data": { "range": 236 },
          "options": null,
          "interventions": []
        },
        {
          "name": "connect",
          "data": {
            "connectionId": "e50815a9-411f-404f-86c0-202912fd8b34",
            "vendorId": "ae1b4468-217e-440d-a2c7-3c44d283a6c1"
          },
          "options": {
            "flow": "oidcProxy",
            "formOptions": [
              {
                "name": "login",
                "type": "login",
                "data": {
                  "url": "https://fleet-auth.prd.vn.cloud.tesla.com/oauth2/v3/authorize?client_id=da4d8a7f845c-4df5-929b-94d3fb60d002&locale={{ locale }}&prompt=login&redirect_uri=https%3A%2F%2Fapp.clever-pv.com%2Foauth2%2Ftesla&response_type=code&scope=openid%20vehicle_device_data%20offline_access%20vehicle_cmds%20vehicle_charging_cmds%20vehicle_location&require_requested_scopes=true&prompt_missing_scopes=true",
                  "redirect": "oauth2/tesla"
                }
              }
            ],
            "docUrl": "https://hemssupport.zendesk.com/hc/de/articles/23043735141394-Tesla-Auto"
          },
          "interventions": []
        }
      ]
    }
  ]
}

---

Step 10: Delete Device

Unlinks a device. Some devices run a full vendor facing reset path (eg.: SG-Ready back to Normal if applicable) that honours force. force does ignore errors on some vendors here.

Code

DELETE /v1/users/{userId}/devices/{deviceId}?force={true|false}

Parameter	Default	Meaning
force (query)	false	If true, only delete locally even when the vendor reset fails. Honoured by a subset of vendors.

Responses:

Status	When
204 No Content	Deleted (always returned when force=true, unless the device doesn't exist).
404 Not Found	No such device for this user.
409 Conflict	force=false and vendor reset failed — device was NOT deleted.

Errorcodes:

code	Meaning
connectionExpired	Refresh token invalid. An authenticationRequired intervention is added to the device's core capability.
deviceUnreachable	Vendor server unreachable. Safe to retry.
resetFailed	Any other vendor error during reset/delete notification.

Code
{
  "code": "deviceUnreachable",
  "message": "Could not reach the manufacturer's server. The device was NOT removed. Use force=true to delete anyway."
}

When to use force=true: eg: the vendor account is gone, the hardware is removed, the connection cannot be restored, or the user has confirmed deletion after a 409. Default to force=false and surface the 409 message so the user can make that choice.

Deleting a whole connection: connections cannot be deleted while devices are linked. Delete each device first (Step 10), then the connection (Step 5).