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:
- Welcome Screen - User gains context on Pelm and Connect
- Utility Selection Screen - User selects their Utility
- Credentials Screen - User inputs their credentials
- 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:
- Backend - Creating a
connect_token
to initialize Connect - Frontend - Initializing and opening Connect
- Backend - Exchanging the
authorization_code
you obtained from Connect for anaccess_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 User
s 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_slug
s and utility_id
s 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.
Parameter | Type | Description |
---|---|---|
connectToken | string | Token generated in step #1. |
onSuccess | (authorizationCode: string) => {} | Called when your User successfully connects their Utility login. |
onExit | (status: string, metadata: any) => {} | Called when Connect is exited. |
The onExit
status
argument is safe for programatic use and can take one of the following values:
token_invalid
: the provided connect_token is invaliduser_initiated_exit
: the user closed Connect by clicking the “x” button or clicking outside the modalunavailable_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
}
access_token
will not expire. You should securely store this token in your database.access_token_expires_in
, refresh_token
, refresh_token_expires_in
. They’re included for legacy applications.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 newUser
s. Your user will see all of the screens listed above.update
mode is used to update existingUser
s 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
.
API Reference
Explore our endpoints