Skip to main content
A client session says who Link acts for and what it may reach, for 60 minutes. Your server creates it with Create a client session and hands its client secret to your app. Link opens any number of link sessions with it until it expires.

​
One endpoint on your server

You write one endpoint, and the SDK calls it through your app:
  1. Your app creates the SDK with a fetchClientSecret callback, once.
  2. When your app opens Link for an action, the SDK calls fetchClientSecret with that action (add, network, …, plus its chargerId or siteId), while the hosted flow loads.
  3. Your callback asks your endpoint, which creates a client session scoped to that action and returns its client_secret.
  4. When the secret runs out while Link is still open, the SDK calls fetchClientSecret again with the same action. Your user can take as long as they need.
If the callback throws, returns an empty string or takes longer than 30 seconds, the hosted flow shows an error screen with Try again. If your user gives up there, Link closes with the error code clientSecretUnavailable. Get started has a complete endpoint in Node.

​
Who it’s for

external_user_id is your own id for the user: 1 to 200 letters, digits and ._:@-. A Plugchoice user who calls the SDK API with their own token always acts for themselves.

​
The scope

The scope is required. It’s everything the client session’s link sessions may reach, so a client secret can’t be used on the rest of your fleet. Name at least one of these:
  • Every id is checked when you create the client session. One that you may not use, or that doesn’t exist, is 404 not-found. A scope can only narrow your access.
  • A scope that names nothing is 422 scope-required. There is no “everything”: to reach a lot, list the sites.
  • With external_user_id, the chargers and sites must be that user’s. Without it, they must be at sites your integration’s team owns.
  • If your app opens an action for a charger or site outside the scope, Link can’t start. It shows an error, and closes with the code not-found.

​
Scope each action

Scope the client session to exactly what the action is about: An add link session goes to the site the app opened it for (siteId, which must be in scope.sites). Without a siteId it goes to the site of location, else to a new site, else to the scope’s only site. A scope with several sites and nothing else needs a siteId (site-required). A scope of chargers only can’t add.

​
Locations

Send a location when you know where your user’s charger is:
  • reference is your own id for the address. A later client session for the same user with the same reference adds to the same site.
  • timezone is an IANA time zone, used for schedules and history.
  • name is Home when you leave it out.
With new_site instead, the hosted flow asks your user for the address before it adds the charger. Once an add link session has made a site, later link sessions of the same client session add to it. The other fields of a client session apply to all of its link sessions:

​
The client secret

  • It starts with cs_test_ for a test integration and cs_live_ for a live one. Otherwise it’s opaque.
  • It works for 60 minutes (expires_at), for any number of link sessions.
  • Plugchoice stores only a hash of it. Don’t log it, and don’t put it in a URL.
  • The SDK never puts it in a URL either: it hands it to the hosted flow directly. In a browser, web_url carries it in the URL fragment, which never reaches a server.