Connect Guide

Connect is a UI component provded by Pelm that allows your users to seamlessly and securely connect their utility login. The end goal of Connect is to obtain an access_token, which grants you access to a particular User’s data.

The Connect flow consists of the following screens:

1. Welcome Screen - User gains context on Pelm and Connect
2. Utility Selection Screen - User selects their Utility
3. Credentials Screen - User inputs their credentials
4. MFA Screen - Only shown for utilities that require multi-factor authentication

​

Setting up Connect

This guide will walk through the following steps to getting Connect set up in your app:

1. Backend - Creating a connect_token to initialize Connect
2. Frontend - Initializing and opening Connect
3. Backend - Exchanging the authorization_code you obtained from Connect for an access_token

​

0. Install Connect

Either install our React library or add a <script> tag.

npm install react-pelm-connect

​

1. Backend - Create a connect_token

The first step is creating a Connect token. This is an extra security measure that abstracts away information like your Pelm-Secret and user_id from the web client.

You must include your own unique identifier for your user in the query parameters. This identifier is required to get User info or delete Users via our /users endpoints.

Include the optional utility_slug parameter if you want your User to skip the Utility Selection Screen. You can find a list of utility_slugs and utility_ids here.

To retrieve a connect_token, make a POST request to the /auth/connect_token endpoint:

import express from "express";
import fetch from "node-fetch";

const app = express();
const port = 3001

app.post('/connect-token', async (req, res) => {
  const headers = new Headers();
  headers.set('Pelm-Client-Id', 'PELM_CLIENT_ID');  // Replace with your 'Pelm-Client-Id'
  headers.set('Pelm-Secret', 'PELM_SECRET');  // Replace with your 'Pelm-Secret'
  const encodedParams = new URLSearchParams();
  encodedParams.set('user_id', 'USER_ID');  // Replace with your 'user_id'
  const requestOptions = {
    method: 'POST',
    headers,
    body: encodedParams,
  };

  const response = await fetch('https://api.pelm.com/auth/connect-token', requestOptions);
  const data = await response.json()
  if (response.ok) {
    res.json({
      'connect_token': data['connect_token']
    })
  } else {
    res.status(500).send(data)
  }
})

app.listen(port, () => {
  console.log(`Server listening on port ${port}`)
})

​

2. Frontend - Initialize Connect

Initialize and open Connect on your frontend.

​

Config object

Pass your connect_token and callbacks to Connect via a config object.

The onExit status argument is safe for programatic use and can take one of the following values:

• token_invalid: the provided connect_token is invalid
• user_initiated_exit: the user closed Connect by clicking the “x” button or clicking outside the modal
• unavailable_utility_credentials_submitted: the user submitted credentials for a utility that Pelm does not yet support

​

Open Connect

Once you’ve created the config object, you can initialize Connect in a few ways.

import { useConnect, Config } from 'react-pelm-connect';

function App() {
  const config: Config = {
    connectToken: 'YOUR_CONNECT_TOKEN',  // connect_token from step 1
    onSuccess: (authorizationCode: string) => {...},
    onExit: (status: string, metadata: any) => {...}
  }

  const { open, ready, error } = useConnect(config);

  return <button
      type="button"
      className="button"
      onClick={() => open()}
      disabled={!ready}
  >
    Connect your utility
  </button>
}

​

3. Backend - Exchange an authorization code for an access token

The final step is exchanging the authorization_code you received in the previous step for an access_token via POST /auth/token.

app.post('/authorization', async (req, res) => {
  const headers = new Headers();
  headers.set('Pelm-Client-Id', 'PELM_CLIENT_ID');  // Replace with your 'Pelm-Client-Id'
  headers.set('Pelm-Secret', 'PELM_SECRET');  // Replace with your 'Pelm-Secret'
  const encodedParams = new URLSearchParams();
  encodedParams.set('code', req.body.authorization_code);  // authorization_code from step 2
  const requestOptions = {
    method: 'POST',
    headers,
    body: encodedParams,
  };

  const response = await fetch('https://api.pelm.com/auth/token', requestOptions);
  const data = await response.json()
  if (response.ok) {
    // save access_token to your database
    // return confirmation to front-end
    res.json({
      'is_successful': true
    })
  } else {
    res.status(500).send(data)
  }
})

You should receive a response that looks like this.

{
  "access_token": "57f20230-4ee7-11ec-9b0c-acde48001122",
  "access_token_expires_in": 3600,  // ignore this
  "refresh_token": "aea9b417e72b3978c5bfcd0782c3a486ec63abf5e85ce9a62ba36d1b18b12488",  // ignore this
  "refresh_token_expires_in": 1314000  // ignore this
}

​

Make your first request

Now that you have your access_token, you can start making requests for your user’s data. Request your User’s accounts via GET /accounts.

This may return the following 500 response:

{
  "error_code": "data_unavailable",
  "message": "We're currently loading data for this account, please try again in 5 minutes."
}

If this happens, wait around one minute and try again.

Note that receiving this response implies that you’ve successfully created an access_token. You can verify this by making the same request with an invalid access_token and receiving a credentials_invalid response.

​

More Connect nuances

Connect has two modes: create or update.

• create mode is used for creating new Users. Your user will see all of the screens listed above.
• update mode is used to update existing Users that have changed their utility password. Your user will start the flow at the Credentials Screen.

The flow is determined by the user_id value you pass when creating a connect_token. We will automatically determine which flow should be shown based on our records for the user.

If you submit a new user_id for a user that has already connected their account with you, your previously submitted user_id will be overwritten by the new value. Make sure you change this appropriately in your records.

​

Next steps

If you want to view an example app that implements the above steps, view our Quickstart Repo.

Visit our API reference to view all the data you can request with your newly created access_token.