Alectra Utilities
Alectra Utilities Green Button Connect My Data (CMD) API

Alectra's mandated Green Button Connect My Data service, required of every Ontario electric and gas utility by Ontario Regulation 633/21 (Energy Data) and implemented to the NAESB REQ.21 Energy Services Provider Interface (ESPI) v3.3 standard. It lets an Alectra account holder authorise the ongoing, secure transfer of their electricity usage and billing data, in the standardised Green Button XML format, to a third party that Alectra has approved. Access is not self-serve: a developer must complete Alectra's third-party registration and onboarding at https://alectrautilitiesonboarding.savagedata.com/ (HTTP 200 on 2026-07-27, a Blazor application titled "3rdPartyRegistration" hosted by Alectra's data custodian vendor Savage Data Systems), accept the Green Button Connect My Data Terms and Conditions of Access and Use, and undertake to follow the Green Button Rules and Standards at greenbuttondata.org, provide a privacy policy and a cybersecurity policy to customers, and use the data only for purposes the customer expressly consented to. No base URI is recorded here because Alectra publishes none — the endpoint is disclosed to approved third parties through onboarding. Alectra's customer Green Button portal at https://alectrautilitiesgbportal.savagedata.com/ returned HTTP 200 on 2026-07-27 and exposes the ESPI path shape /DataCustodian/espi/1_1/resource/..., but that could not be treated as proof: every path on that host, including a bogus control path, HTTP 302 redirects to /Connect/Authorize, a customer sign-in form asking for account name and phone number. The OpenAPI carried in properties[] is the Green Button Alliance's own documentation of the CMD ESPI API, harvested verbatim with provenance — it is the standard's contract, not Alectra's.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.0.0",
  "info": {
    "title": "Green Button API Documentation",
    "description": "Green Button API - ESPI 4.0",
    "version": "1.0.0",
    "contact": {
      "name": "Green Button Alliance",
      "url": "https://www.greenbuttonalliance.org"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "x-provenance": "Shared Green Button Alliance OpenAPI documentation of the Green Button Connect My Data (CMD) ESPI API. NOT Alectra-authored and NOT an Alectra endpoint. Alectra Utilities publishes no first-party OpenAPI, no developer portal and no CMD base URI. It is included here because Alectra is a Green Button data custodian under Ontario Regulation 633/21 and its Green Button portal at https://alectrautilitiesgbportal.savagedata.com/ exposes the same /DataCustodian/espi/1_1/resource/ path shape described by this document -- though that could not be confirmed, because every path on that host (including a deliberately bogus control path) HTTP 302 redirects to /Connect/Authorize, a customer sign-in asking for account name and phone number. The servers[] entry below is the Green Button Alliance public sandbox, not Alectra.",
    "x-source-url": "https://raw.githubusercontent.com/GreenButtonAlliance/OpenAPI-Green-Button-Documentation/main/green-button-openapi.json",
    "x-harvested": "2026-07-27",
    "x-harvest-http-status": 200,
    "x-standard": "Green Button / NAESB REQ.21 Energy Services Provider Interface (ESPI)",
    "x-mandate": "Ontario Regulation 633/21 (Energy Data), filed 2021-09-02, in force 2021-11-01, implementation deadline 2023-11-01"
  },
  "servers": [
    {
      "url": "https://sandbox.greenbuttonalliance.org:8443/DataCustodian",
      "description": "GBA Green Button Sandbox"
    }
  ],
  "components": {
    "schemas": {
      "ApplicationInformation": {
        "type": "object",
        "description": "Contains information about a Third Party Application requesting access to DataCustodian services",
        "xml": {
          "name": "ApplicationInformation",
          "namespace": "http://naesb.org/espi"
        },
        "properties": {
          "dataCustodianId": {
            "type": "string",
            "description": "Identifier for the Data Custodian"
          },
          "dataCustodianApplicationStatus": {
            "type": "integer",
            "description": "Current status of the application (provided by Data Custodian)"
          },
          "thirdPartyApplicationDescription": {
            "type": "string",
            "description": "Description of the Third Party Application"
          },
          "thirdPartyApplicationStatus": {
            "type": "integer",
            "description": "Current status of the Third Party Application"
          },
          "thirdPartyApplicationType": {
            "type": "integer",
            "description": "Type of application (1=Web, 2=Desktop, 3=Mobile, 4=Device)"
          },
          "thirdPartyApplicationUse": {
            "type": "integer",
            "description": "Expected use of the application"
          },
          "client_name": {
            "type": "string",
            "description": "Name of the application (OAuth client_name)"
          },
          "client_id": {
            "type": "string",
            "description": "Identifier for the Third Party (OAuth client_id)"
          },
          "client_secret": {
            "type": "string",
            "description": "Secret for the client (OAuth client_secret)"
          },
          "redirect_uri": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "OAuth redirect URIs"
          },
          "scope": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "OAuth scopes"
          },
          "grant_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Supported OAuth grant types"
          }
        }
      },
      "Authorization": {
        "type": "object",
        "description": "Represents a permission granted by an owner for access to a resource",
        "xml": {
          "name": "Authorization",
          "namespace": "http://naesb.org/espi"
        },
        "properties": {
          "status": {
            "type": "integer",
            "description": "Status of the authorization (0=Revoked, 1=Active, 2=Denied)"
          },
          "expires_at": {
            "type": "integer",
            "format": "int64",
            "description": "Expiration period for the access token (Unix timestamp)"
          },
          "grant_type": {
            "type": "string",
            "description": "Type of grant being negotiated"
          },
          "scope": {
            "type": "string",
            "description": "Negotiated scope of the authorization"
          },
          "token_type": {
            "type": "string",
            "description": "Type of token (Bearer)"
          },
          "resourceURI": {
            "type": "string",
            "format": "uri",
            "description": "URI to access the authorized resource"
          },
          "authorizationURI": {
            "type": "string",
            "format": "uri",
            "description": "URI to update or delete this authorization"
          },
          "customerResourceURI": {
            "type": "string",
            "format": "uri",
            "description": "URI to access PII data authorized for this customer"
          }
        }
      },
      "UsagePoint": {
        "type": "object",
        "description": "Logical point on a network at which consumption or production is measured or estimated",
        "xml": {
          "name": "UsagePoint",
          "namespace": "http://naesb.org/espi"
        },
        "properties": {
          "roleFlags": {
            "type": "string",
            "description": "Specifies roles assigned to this usage point"
          },
          "ServiceCategory": {
            "type": "integer",
            "description": "Category of service (0=electricity, 1=gas, 2=water, etc.)"
          },
          "status": {
            "type": "integer",
            "description": "Current status (0=off, 1=on)"
          },
          "isSdp": {
            "type": "boolean",
            "description": "Whether this is a service delivery point"
          },
          "isVirtual": {
            "type": "boolean",
            "description": "Whether this is a virtual (logical) usage point"
          },
          "connectionState": {
            "type": "string",
            "description": "Connection state relative to network"
          }
        }
      },
      "AtomLink": {
        "type": "object",
        "description": "Atom link element (RFC 4287)",
        "xml": {
          "name": "link",
          "namespace": "http://www.w3.org/2005/Atom"
        },
        "properties": {
          "href": {
            "type": "string",
            "format": "uri",
            "description": "Link URI"
          },
          "rel": {
            "type": "string",
            "description": "Link relationship type (e.g., 'self', 'up')"
          },
          "type": {
            "type": "string",
            "description": "Media type (e.g., 'application/atom+xml')"
          }
        }
      },
      "AtomContent": {
        "type": "object",
        "description": "Atom content element containing ESPI resource (RFC 4287)",
        "xml": {
          "name": "content",
          "namespace": "http://www.w3.org/2005/Atom"
        },
        "properties": {
          "type": {
            "type": "string",
            "description": "Content media type (typically 'application/xml')"
          }
        }
      },
      "AtomEntry": {
        "type": "object",
        "description": "Atom feed entry (RFC 4287) containing ESPI resource",
        "xml": {
          "name": "entry",
          "namespace": "http://www.w3.org/2005/Atom"
        },
        "properties": {
          "id": {
            "type": "string",
            "format": "uri",
            "description": "Unique entry identifier"
          },
          "title": {
            "type": "string",
            "description": "Entry title"
          },
          "published": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 publication timestamp"
          },
          "updated": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 last update timestamp"
          },
          "link": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtomLink"
            },
            "description": "Entry links (minimum 2 required per Atom spec)"
          },
          "content": {
            "$ref": "#/components/schemas/AtomContent"
          }
        }
      },
      "AtomFeed": {
        "type": "object",
        "description": "Atom Feed (RFC 4287) containing ESPI resources",
        "xml": {
          "name": "feed",
          "namespace": "http://www.w3.org/2005/Atom"
        },
        "properties": {
          "id": {
            "type": "string",
            "format": "uri",
            "description": "Feed identifier"
          },
          "title": {
            "type": "string",
            "description": "Feed title"
          },
          "updated": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of last feed update"
          },
          "link": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtomLink"
            },
            "description": "Feed links (minimum 1 required per Atom spec)"
          },
          "entry": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtomEntry"
            },
            "description": "Feed entries containing ESPI resources"
          }
        }
      }
    },
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://sandbox.greenbuttonalliance.org:8443/oauth/authorize",
            "tokenUrl": "https://sandbox.greenbuttonalliance.org:8443/oauth/token",
            "scopes": {}
          },
          "clientCredentials": {
            "tokenUrl": "https://sandbox.greenbuttonalliance.org:8443/oauth/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "ApplicationInformation",
      "description": "Application Information endpoints"
    },
    {
      "name": "Authorization",
      "description": "Authorization endpoints"
    },
    {
      "name": "Batch",
      "description": "Batch data transfer endpoints"
    },
    {
      "name": "UsagePoint",
      "description": "Usage Point endpoints"
    }
  ],
  "paths": {
    "/espi/1_1/resource/ApplicationInformation": {
      "get": {
        "tags": [
          "ApplicationInformation"
        ],
        "summary": "Retrieve all Application Information [FB_33]",
        "operationId": "findApplicationInformations",
        "parameters": [
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/ApplicationInformation/{applicationInformationId}": {
      "get": {
        "tags": [
          "ApplicationInformation"
        ],
        "summary": "Retrieve Application Information by Id [FB_3]",
        "operationId": "getApplicationInformation",
        "parameters": [
          {
            "name": "applicationInformationId",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the ApplicationInformation resource",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationInformation"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationInformation"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/Authorization": {
      "get": {
        "tags": [
          "Authorization"
        ],
        "summary": "Find all Authorizations [FB_3]",
        "operationId": "findAuthorizations",
        "parameters": [
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/Authorization/{authorizationId}": {
      "get": {
        "tags": [
          "Authorization"
        ],
        "summary": "Retrieve Authorization by Id [FB_3]",
        "operationId": "getAuthorization",
        "parameters": [
          {
            "name": "authorizationId",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the Authorization resource",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/Authorization"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/Authorization"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/Batch/Bulk/{bulkId}": {
      "get": {
        "tags": [
          "Batch"
        ],
        "summary": "Request Bulk transfer [FB_35]",
        "operationId": "downloadBulkData",
        "parameters": [
          {
            "name": "bulkId",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the Bulk transfer",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/UsagePoint": {
      "get": {
        "tags": [
          "UsagePoint"
        ],
        "summary": "Retrieve all Usage Points [FB_33]",
        "operationId": "findUsagePoints",
        "parameters": [
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/AtomFeed"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/espi/1_1/resource/UsagePoint/{usagePointId}": {
      "get": {
        "tags": [
          "UsagePoint"
        ],
        "summary": "Retrieve Usage Point by Id [FB_32]",
        "operationId": "getUsagePoint",
        "parameters": [
          {
            "name": "usagePointId",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the UsagePoint resource",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "published-max",
            "in": "query",
            "description": "Maximum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "published-min",
            "in": "query",
            "description": "Minimum publication date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-max",
            "in": "query",
            "description": "Maximum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "updated-min",
            "in": "query",
            "description": "Minimum update date (RFC 3339 instant)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "max-results",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "start-index",
            "in": "query",
            "description": "Index of first result (1-indexed)",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "depth",
            "in": "query",
            "description": "Response depth control",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/UsagePoint"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "$ref": "#/components/schemas/UsagePoint"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    }
  }
}
Alectra Utilities Green Button Connect My Data (CMD) API

Documentation

Specifications

Other Resources

OpenAPI Specification
