Introduction

The Super Connect REST API allows you to programmatically interact with the Super Connect data platform. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The Super Connect API adheres to the JSON:API v1.0 specification.

Base URL

The base URL for all incoming requests is: https://api.thesuperconnect.com/v1.

Health check

To check the health of the API, a GET request to the endpoint / should return a 200 OK HTTP status code with a StatusResource schema. No authentication or specific headers are required.

Client requirements

HTTPS

All requests must be made over HTTPS.

Required headers

All requests must contain the header Accept: application/vnd.api+json or they will be rejected by the server as an ErrorResponse with a 406 Not Acceptable HTTP status code.

Requests to endpoints which require authentication must contain a valid bearer token in the header as: Authorization: Bearer {token} or they will be rejected by the server as an ErrorResponse with a 401 Unauthorized HTTP status code.

For documentation on how to obtain a bearer token, see login.

Authorization

Requests to endpoints to which the current user does not have authorization will be rejected by the server as an ErrorResponse with a 403 Forbidden HTTP status code.

Rate limits

Rate limits are in place as a defensive measure against intended or unintended excessive use. The Super Connect API has a rate limit for authenticated users of 50 requests per minute, which is sufficient for typical use.

Requests that exceed the rate limit will will be rejected by the server as an ErrorResponse with a 429 Too Many Requests HTTP status code, along with the Retry-After: NUMBER_OF_SECONDS header containing the number of seconds to wait until another request can be made.

The returned HTTP headers of all API requests show your current rate limit status, e.g.:


                                X-RateLimit-Limit: REQUESTS_PER_MINUTE_LIMIT
                                X-RateLimit-Remaining: REQUESTS_PER_MINUTE_REMAINING
                                X-RateLimit-Reset: NUMBER_OF_SECONDS_UNTIL_ZERO

HTTP response codes

The Super Connect API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx range indicate an internal error with the Super Connect API (these are rare).

Bad requests (e.g., invalid body or parameters), will be rejected by the server as an ErrorResponse with a 400 Bad Request HTTP status code. Requests that receive a 400 Bad Request response should not be repeated without modifications.

If the API is temporarily undergoing maintenance or repairs, the request will be rejected by the server as an ErrorResponse with a 503 Service Unavailable HTTP status code, along with the Retry-After: NUMBER_OF_SECONDS header containing the number of seconds to wait until the server is expected to become available.

HTTP response codes in the 4xx and 5xx range will always be returned as an ErrorResponse.

Collection pagination

Resource collection endpoints will return a maximum of 20 results by default. Pagination can be managed using the page[size] and page[number] query parameters.

For example, adding the query string ?page[size]=10&page[number]=3 to the endpoint URL would return a maximum of 10 results, beginning with the 30th item.

The maximum number of results allowed to be returned in a single request is 10000.

Sparse fieldsets

This API supports returning only specific fields in the response on a per-type basis. Limiting the returned fields to only those which are needed is extremely helpful in reducing the payload size and API response times.

Example

When getting providers, you may limit the fields returned in the ElectricProviderCollection schema as follows:


                    /electric/providers?fields[electricProviders]=name,state

The above example would only return the name and state for each electric provider.

For more information, see JSON:API sparse fieldsets.

Sorting and filtering

Resource collection endpoints support custom sorting and filtering based on any of the supported fields for that collection.

Sorting example

When getting providers, you may sort the ElectricProviderCollection schema as follows:


                    /electric/providers?sort=state,-name

The above example would sort the electric providers by state in ascending order, then by name in descending order.

For more information, see JSON:API sorting.

Filtering example

When getting providers, you may filter the ElectricProviderCollection schema as follows:


                    /electric/providers?filter[state][eq]=fl

The above example would filter the electric providers to only return those whose state equals fl.

The format for filtering is: filter[:field][:operator]=value.

Supported filter operators include:

  • eq (equals)
  • !eq (does not equal)
  • lt (less than)
  • gt (greater than)
  • le (less than or equal to)
  • ge (greater than or equal to)
  • sw (starts with)
  • !sw (does not start with)
  • ew (ends with)
  • !ew (does not end with)
  • has (has)
  • !has (does not have)
  • in (in)
  • !in (not in)
  • null (is or is not null)

The in and !in operators accept multiple comma-separated values.

The null operator accepts two values: true and false for is null or is not null.

Authentication

Login

Users must be authenticated before they can interact with the Super Connect API.

Authentication is performed by submitting your credentials to the API's login endpoint. A successful request will return a JWT-encoded access token with a 2 hour validity, which must then be submitted in the header as: Authorization: Bearer {token} of any subsequent requests to the API.

Failed login attempts are limited to 5 requests per minute.

For more information, see Client requirements.

Notice:
Both access and refresh tokens can be used to gain access to your account. Keep them secure.

Request

POST /auth/login
Parameter In Type Required Description
Content-Type header string true application/vnd.api+json
body string true AuthLoginRequest

Response

HTTP Status Title Description Schema
200 OK Authentication successful AuthResource

Refresh token

A new access token can be created without having to login again by sending an existing access token along with the last refresh token issued. Refresh tokens are valid for 7 days after they were issued.

Failed refresh token requests are limited to 5 requests per minute.

Request

POST /auth/refresh
Parameter In Type Required Description
Content-Type header string true application/vnd.api+json
body string true AuthRefreshRequest

Response

HTTP Status Title Description Schema
200 OK Authentication successful AuthResource

Account management

Role-based access

Super connect users are granted role-based access to the API. Permissions will vary based on which role a user has been granted.

Users may be assigned to any of the following roles:

Group Administrator

A Group Administrator has read+write access to all users within their group. In addition, a Group Administrator is able to create connections on behalf of any users within their group.

Group Administrators are also able to create new users.

Group Member

A Group Member has read+write access to their own account, and read-only access to users within their group. In addition, a Group Member is able to create connections on behalf of themselves only.

Group User

A Group User has read+write access to their own account, and have no access to any other users besides themselves. In addition, a Group User is able to create connections on behalf of themselves only.

Get groups

Retrieve a collection of groups.

Request

GET /groups

Response

HTTP Status Title Description Schema
200 OK Successful request GroupCollection

Get group

Retrieve a single group.

Request

GET /groups/:id
Parameter In Type Required Description
id path string true Group ID

Response

HTTP Status Title Description Schema
200 OK Successful request GroupResource
404 Not found Group not found ErrorResponse

Get group users

Retrieve a collection of users in a single group.

Request

GET /groups/:id/users
Parameter In Type Required Description
id path string true Group ID

Response

HTTP Status Title Description Schema
200 OK Successful request UserCollection
404 Not found Group not found ErrorResponse

Manage group users

Read and update group users relationships.

Request

/groups/:id/relationships/users
HTTP Method Description Schema
POST Add users to group ToManyRelationshipRequest
GET Get users in group ToManyRelationshipResponse
PATCH Replace all users in group ToManyRelationshipRequest
DELETE Remove users from group ToManyRelationshipRequest

Get permissions

Retrieve a collection of permissions.

Request

GET /permissions

Response

HTTP Status Title Description Schema
200 OK Successful request PermissionCollection

Get permission

Retrieve a single permission.

Request

GET /permissions/:id
Parameter In Type Required Description
id path string true Permission ID

Response

HTTP Status Title Description Schema
200 OK Successful request PermissionResource
404 Not found Permission not found ErrorResponse

Get roles

Retrieve a collection of roles.

Request

GET /roles

Response

HTTP Status Title Description Schema
200 OK Successful request RoleCollection

Get role

Retrieve a single role.

Request

GET /roles/:id
Parameter In Type Required Description
id path string true Role ID

Response

HTTP Status Title Description Schema
200 OK Successful request RoleResource
404 Not found Role not found ErrorResponse

Get role permissions

Retrieve a collection of permissions granted to a single role.

Request

GET /roles/:id/permissions
Parameter In Type Required Description
id path string true Role ID

Response

HTTP Status Title Description Schema
200 OK Successful request PermissionCollection
404 Not found Role not found ErrorResponse

Working with self

A number of endpoints exist to make working with the current user easier. They are as follows:

HTTP Method Endpoint Description
GET /me Alias of get user
PATCH /me Alias of update user
GET /me/groups Alias of get user groups
GET /me/permissions Alias of get user permissions
GET /me/roles Alias of get user roles

Create user

Create user. The returned UserResource schema will reflect the new user.

Request

POST /users
Parameter In Type Required Description
Content-Type header string true application/vnd.api+json
body string true UserCreateRequest

Response

HTTP Status Title Description Schema
201 Created User created UserResource
409 Conflict Email already exists or field mismatch ErrorResponse

Get users

Retrieve a collection of users.

Request

GET /users

Response

HTTP Status Title Description Schema
200 OK Successful request UserCollection

Get user

Retrieve a single user.

Request

GET /users/:id
Parameter In Type Required Description
id path string true User ID

Response

HTTP Status Title Description Schema
200 OK Successful request UserResource
404 Not found User not found ErrorResponse

Update user

Update user. The returned UserResource schema will reflect the updates made.

Request

PATCH /users/:id
Parameter In Type Required Description
Content-Type header string true application/vnd.api+json
id path string true User ID
body string true UserUpdateRequest

Response

HTTP Status Title Description Schema
200 OK Successful request UserResource
404 Not found User not found ErrorResponse
409 Conflict Email already exists or field mismatch ErrorResponse

Get user groups

Retrieve a collection groups to which a single user has been assigned.

Request

GET /users/:id/groups
Parameter In Type Required Description
id path string true User ID

Response

HTTP Status Title Description Schema
200 OK Successful request GroupCollection
404 Not found User not found ErrorResponse

Manage user groups

Read and update user groups relationships.

Request

/users/:id/relationships/groups
HTTP Method Description Schema
POST Add groups to user ToManyRelationshipRequest
GET Get groups of user ToManyRelationshipResponse
PATCH Replace all groups of user ToManyRelationshipRequest
DELETE Remove user from groups ToManyRelationshipRequest

Get user permissions

Retrieve a collection permissions granted to a single user.

User permissions become the union of all the permissions granted to the roles to which they are assigned.

Request

GET /users/:id/permissions
Parameter In Type Required Description
id path string true User ID

Response

HTTP Status Title Description Schema
200 OK Successful request PermissionCollection
404 Not found User not found ErrorResponse

Get user roles

Retrieve a collection roles granted to a single user.

Request

GET /users/:id/roles
Parameter In Type Required Description
id path string true User ID

Response

HTTP Status Title Description Schema
200 OK Successful request RoleCollection
404 Not found User not found ErrorResponse

Manage user roles

Read and update user roles relationships.

Request

/users/:id/relationships/roles
HTTP Method Description Schema
POST Grant role to user ToManyRelationshipRequest
GET Get roles of user ToManyRelationshipResponse
PATCH Replace all roles of user ToManyRelationshipRequest
DELETE Revoke user from roles ToManyRelationshipRequest

Electric providers

Get providers

Retrieve a collection of all electric providers with which an electric connection can be performed.

Request

GET /electric/providers

Response

HTTP Status Title Description Schema
200 OK Successful request ElectricProviderCollection

Get provider

Retrieve a single electric provider.

Request

GET /electric/providers/:id
Parameter In Type Required Description
id path string true Provider ID

Response

HTTP Status Title Description Schema
200 OK Successful request ElectricProviderResource
404 Not found Provider not found ErrorResponse

Electric connections

Create connection

Creating an electric connection allows you to submit a connection request for a single electric utility account with a supported electric provider.

Once an electric connection is created, it cannot be modified. A new connection must be created with the updated information.

Request

POST /electric/connections
Parameter In Type Required Description
Content-Type header string true application/vnd.api+json
body string true ElectricConnectionRequest

Response

HTTP Status Title Description Schema
201 Created Connection created ElectricConnectionResource
404 Not found Provider ID/User ID not found ErrorResponse
409 Conflict Field mismatch ErrorResponse

Get connections

Retrieve a collection of all electric connections created with your account.

Note:
Failed electric connections are automatically deleted after 7 days.

Request

GET /electric/connections

Response

HTTP Status Title Description Schema
200 OK Successful request ElectricConnectionCollection

Get connection

Retrieve a single electric connection. Available data returned may vary depending on the connection's status and the electric provider.

Note:
Failed electric connections are automatically deleted after 7 days.

Request

GET /electric/connections/:id
Parameter In Type Required Description
id path string true Connection ID

Response

HTTP Status Title Description Schema
200 OK Successful request ElectricConnectionResource
404 Not found Connection not found ErrorResponse

Schemas

AuthLoginRequest
Name Type Required Description
email string true Email address associated with your Super Connect account
password string true Your Super Connect account password

AuthRefreshRequest
Name Type Required Description
accessToken string true A previously issued access token
refreshToken string true The refresh token given from the last AuthResource response

AuthResource
Name Type Required Description
accessToken string true Access token (JWT)
refreshToken string true Refresh token
type string true Token type
expiresIn string true Seconds until access token expires
expiresAt string true UTC timestamp when access token expires

ElectricConnectionCollection
Name Type Required Description
data array false Array of matching ElectricConnectionResource schemas
meta.results object true ResourceCollectionMetaResults schema
links object true ResourceCollectionPagination schema

ElectricConnectionRequest
Name Type Required Description
providerId string true id field from the ElectricProviderResource schema
userId string true id field from the UserResource schema
credentials.username string true Electric provider account username
credentials.password string true Electric provider account password
account.number string false Electric provider account number
correlationId string false Correlation ID to be associated with this connection
Note:
Submitting the account number is optional, and only necessary if the given credentials manages more than one account with the electric provider.

ElectricConnectionResource
Name Type Required Description
userId string true id field from the UserResource schema
providerId string true id field from the ElectricProviderResource schema
status string true Current status. Possible values of: PENDING, SUCCESS, CANCELLED, or FAILED
statusDetail string false Additional details regarding current status
account object false Account details with the electric provider
statements array false Array of available statements ordered from oldest to most recent. Up to 12 statements may be returned.
solarRadiation object false Average monthly solar radiation values for this address (kWh/m2/day)
correlationId string false correlationId provided in the ElectricConnectionRequest schema when the connection was created
createdAt string false ISO 8601 format date/time UTC
updatedAt string false ISO 8601 format date/time UTC

ElectricProviderCollection
Name Type Required Description
data array false Array of matching ElectricProviderResource schemas
meta.results array true ResourceCollectionMetaResults schema
links array true ResourceCollectionPagination schema

ElectricProviderResource
Name Type Required Description
name string false Provider name
state string false Provider state
url string false Provider URL
fields object false Field labels used by provider for username and password
createdAt string false ISO 8601 format date/time UTC
updatedAt string false ISO 8601 format date/time UTC

ErrorResponse
Name Type Required Description
status string true HTTP status code
title string true Error title
detail string false Additional details regarding the error
code string false Unique code used to reference this error

GroupCollection

Name Type Required Description
data array false Array of matching GroupResource schemas
meta.results object true ResourceCollectionMetaResults schema
links object true ResourceCollectionPagination schema

GroupResource

Name Type Required Description
name string true Group name
createdAt string false ISO 8601 format date/time UTC
updatedAt string false ISO 8601 format date/time UTC

PermissionCollection

Name Type Required Description
data array false Array of matching PermissionResource schemas
meta.results object true ResourceCollectionMetaResults schema
links object true ResourceCollectionPagination schema

PermissionResource

Name Type Required Description
name string true Permission name
description string false Description

ResourceCollectionMetaResults
Name Type Required Description
count integer true Number of resources returned for the current page
total integer true Total number of resources available for the current collection
pages integer true Total number of pages for the current collection
pageSize integer true Maximum number resources returned per page
pageNumber integer true Current page number

ResourceCollectionPagination
Name Type Required Description
self string true URL to current page
first string true URL to the first page of the collection
prev string false URL to the previous page of the collection
next string false URL to the next page of the collection
last string true URL to the last page of the collection

RoleCollection

Name Type Required Description
data array false Array of matching RoleResource schemas
meta.results object true ResourceCollectionMetaResults schema
links object true ResourceCollectionPagination schema

RoleResource

Name Type Required Description
name string true Role name
enabled boolean true Is role enabled
createdAt string false ISO 8601 format date/time UTC
updatedAt string false ISO 8601 format date/time UTC

StatusResource
Name Type Required Description
status string true API status description
version string true API version

ToManyRelationshipRequest
Name Type Required Description
data array true Array of resource identifier objects

For more information, see: Updating To-Many Relationships.

ToManyRelationshipResponse
Name Type Required Description
data array true Array of resource identifier objects
meta.results object true ResourceCollectionMetaResults schema
links object true ResourceCollectionPagination schema

For more information, see: Fetching Relationships.

UserCollection

Name Type Required Description
data array false Array of matching UserResource schemas
meta.results object true ResourceCollectionMetaResults schema
links object true ResourceCollectionPagination schema

UserCreateRequest
Name Type Required Description
email string false Email
password string true Password
firstName string false First name
lastName string false Last name
companyName string false Company name

UserResource
Name Type Required Description
email string false Email
firstName string false First name
lastName string false Last name
companyName string false Company name
enabled boolean false Is user enabled
createdAt string false ISO 8601 format date/time UTC
updatedAt string false ISO 8601 format date/time UTC

UserUpdateRequest
Name Type Required Description
email string false Email
password string false Password
firstName string false First name
lastName string false Last name
companyName string false Company name

Miscellaneous

Changelog

Coming soon

  • Ability to provide a webhook URL to be notified of status changes for an electric connection

v1.0.0 - 2021.03.03

Added
  • Initial release