What is Connect?
Connect is the embeddable component that allows you to create a connection to your customers' utility account data in your application. A utility provider connection made through the Connect workflow is required for your app to use the functionality of Arcadia’s Plug, Bundle, and Spark (Connect is NOT needed for Signal and Switch).
Connect does an authentication handshake with customers’ utility providers, using account credentials provided by the customer.
What do I need to do to get ready for Connect?
- Get access to Arcadia Platform’s developer dashboard, where you’ll be able to access our API documentation, our quickstart guide, and get your sandbox API keys.
- Walkthrough the Arcadia demo, which includes Connect.
- View Connect’s npm package.
How it works
You will present Connect to your customers in your application when you would like to create or update a connection to that customer’s utility provider. This connection is the foundation of all of Arcadia Platform’s functionality and is required to use Plug, Bundle, or Spark for your customers.
The Connect component is an easy-to-use UI that enables your customers to grant Arcadia consent to get their utility data, and then to enter the information needed to retrieve that data.
When to present Connect
Your app should present Connect to your customers in two different cases:
- When you’d like to create a connection to one of your customer’s utility providers (either for the first time, or subsequent times if they have accounts with more than one utility provider)
- When you need to update an existing connection to a customer’s utility provider (typically done for customers that have changed their utility account password)
Creating a connection to a customer’s utility provider
When you would like to use Arcadia features for one of your customer’s utility accounts, your app must make a connection to that account using Arcadia Platform’s Connect component.
Arcadia Platform can start getting your customer’s data as soon as they input the needed authentication information (typically a utility username and password) through the Connect workflow.
Getting a Connect Token to initialize Connect
A session of Connect is initialized with a Connect Token, which scopes the session to a specific user when creating new utility provider connection. Below are the steps to create that token.
- Obtain an access token
- Retrieve the unique ID for your customer from your system. If you don’t already have one, it’s recommended you provide and persist a UUID. This ID will be used in Connect and the other Arcadia Platform endpoints as the client_user_id parameter.
- Obtain a Connect token using the client_user_id and the access token in the authorization header. In this use case the value of the utility_credential_id parameter, which is used when the customer changes their utility provider credentials, must be left empty.
- Initialize the Connect React component with the Connect token. With the Connect token, the Connect session is scoped to the customer using your app, and all accounts at the utility provider connected to in the session will be associated with the customer’s client_user_id.
- Connect prompts the customer to enter the data needed to authenticate with their utility provider:
- First, the customer consents to allow your app (and Arcadia Platform Connect) to access their utility data. The consent includes detail on which data is obtained and a link to detailed terms and conditions.
- Next, they indicate their utility provider by entering their zip code and accepting the pre-populated option or selecting from the drop-down list.
- Finally, they supply their login credentials for the chosen utility provider. 2FA authentication is supported for a number of utilities that have implemented it.
- Arcadia Platform sends along the customer's credentials to the utility provider for authentication.
- Arcadia Platform verifies the credentials with the utility provider and Connect displays the results to the customer. In addition, Arcadia Platform sends a webhook message with the results of the authentication. You can also poll the API. The possible authentication statuses possible are: verified, rejected, timeout, error, and pending. If pending, the result will be sent via a webhook message when ready.
At this point, Connect will return the newly created utility_credential_id to the hosting front-end application. You can use this information to poll for updates to the Utility Credential, or just listen for any changes via a webhook message.
Updating a customer’s utility connection
Arcadia Platform regularly checks the customer’s utility provider’s records for new statements. If the customer changes their password (or other credential information) with the utility provider, the next lookup by Arcadia Platform will fail.
If this happens, Arcadia Platform will notify your systems via a webhook message called utility_credential_revoked. This webhook message contains the utility_credential_id mentioned in the previous section.
The next time your customer uses your app, the app should prompt the customer to update their utility credential information by:
- Requesting an Auth token
- Requesting a Connect token with the utility_credential_id as a parameter instead of the client_user_id (The utility_credential_id represents the specific connection between your customer and the utility you are trying to update connection for)
- Initializing the Connect component with the Connect token. Because utility_credential_id was used to generate a Connect Token instead of client_user_id, the session of Connect with initialize in ‘update mode’.
At that point the UI will prompt the customer to enter their new utility provider credentials in an effort to update the broken connection. The zip code and utility selection steps of the Connect workflow will be skipped, as they are already known for the specific utility_credential_id.
Should authentication with the new credentials succeed, Arcadia Platform will resume its regular statement checks and collection.
For more information…
- Try the Arcadia demo to see Connect in action
- Read the Connect React documentation
- Read the rest of the API documentation