Green Button OAuth: how CMD authorization works

Download My Data is a one time export. Connect My Data (CMD) is a standing arrangement: a customer grants a third party permission to fetch their utility data automatically, on an ongoing basis, until that permission is withdrawn. That difference is entirely about authorization, and Green Button handles it with OAuth 2.0. If you are building software that keeps energy data fresh, the OAuth flow is the part you cannot skip.

This article walks through how that authorization works: who the parties are, how consent is captured, what scopes control, how tokens are issued and refreshed, and how access ends when a customer changes their mind.

The standards CMD is built on

Green Button Connect My Data combines the NAESB REQ.21 ESPI data model with two IETF standards: The OAuth 2.0 Authorization Framework (RFC 6749) and OAuth 2.0 Bearer Token Usage (RFC 6750). In practice this means the data model is Green Button specific, but the authorization and the API calls use the same OAuth patterns that developers already know from other web APIs.

The three parties

CMD involves three roles. Getting them straight makes the rest of the flow clear:

• Data Custodian: the utility that holds the meter data and runs the OAuth authorization server and the resource API.
• Third Party: the application requesting data, which registers with the Data Custodian ahead of time and receives client credentials.
• Retail Customer: the account holder who authorizes the Third Party to access their data and who can revoke that access later.

Registration and the ApplicationInformation resource

Before any customer consent happens, the Third Party registers with the Data Custodian. That registration is represented by an ApplicationInformation resource, which holds the client identifier, the client secret, the redirect URI, and the scopes the application is allowed to request. Some housekeeping calls, such as reading the ApplicationInformation itself, use the OAuth client credentials grant rather than a customer authorization.

The consent and token flow

The customer facing part uses the OAuth authorization code grant. The sequence looks like this:

1. The Third Party redirects the customer to the Data Custodian's authorization endpoint, passing its client identifier and the requested scope.
2. The customer authenticates with their utility and sees a consent screen describing what will be shared and for how long.
3. On approval, the Data Custodian redirects back to the Third Party's registered redirect URI with a short lived authorization code.
4. The Third Party exchanges that code at the token endpoint for an access token and a refresh token.
5. The Third Party calls the resource API for the customer's usage data, presenting the access token as a bearer token.

The access token is what authorizes each data request. Because CMD is meant to keep working over months, the refresh token exists so the Third Party can obtain new access tokens without sending the customer back through the consent screen every time.

Scopes decide what you can see

The scope parameter is where CMD gets specific about data. Green Button scopes are compound strings assembled from function block, value, and resource terms rather than simple comma separated words. The ApplicationInformation resource lists the scopes a Data Custodian offers, and a granted scope for a given authorization may be a subset of what was offered. Function block (FB) codes identify capability areas, so a scope can name interval data, billing period grouping, an interval duration such as 900 seconds for 15 minutes or 3600 for one hour, and how many accounts are covered. Requesting only the scope you need is good practice, because it limits the token to the necessary data.

Token lifetimes and refresh

Because the data is sensitive and includes personal information, Green Button guidance favors short lived access tokens. The Green Button Alliance suggests access token lifespans on the order of 5 to 15 minutes and longer lived refresh tokens measured in days to weeks, with refresh tokens rotated over time. Short access tokens limit the damage if one is intercepted, while the refresh token keeps the ongoing connection alive. Your integration needs to handle the refresh cycle cleanly, catching expired tokens and requesting new ones without dropping data collection.

What the token guidance actually recommends

The standard sets the mechanics, but the Green Button Alliance publishes guidance on how long tokens should live, because energy usage data carries personally identifiable information. Its guidance on access and refresh token duration recommends short access token lifespans of 5 to 15 minutes, so an intercepted token is useful for a brief window only, and long refresh token lifespans measured in days to weeks, rotated every time they are used.

The same guidance is specific about when to revoke: on logout, on data updates, and on permission changes, with refresh tokens otherwise left alone until the customer or the utility revokes authorization or the token expires. It also expects TLS for every exchange, encrypted storage for tokens at rest, and a revocation endpoint you can call immediately if a token is compromised. Those are the details that separate an integration that passes a security review from one that does not.

The practical consequence for anyone building this: your sync process cannot assume a token it fetched this morning still works this afternoon. Refresh has to be part of the normal request path, not an error handler bolted on later.

Where CMD integrations break in production

The authorization flow is well documented and reasonably straightforward to implement once. Keeping it working across dozens or hundreds of customer authorizations, at several utilities, is where the effort actually goes. The failures that cost the most time are rarely exotic:

• Silent revocation. A customer changes their utility password, closes an account, or withdraws consent in the utility portal. Your next call returns an authorization error rather than data. Without monitoring per authorization, you find out when someone notices a gap in a report weeks later.
• Refresh token rotation. If the utility rotates the refresh token on each use, storing the old one means the next refresh fails. This is the single most common cause of an integration that works in testing and dies in week three.
• Scope too narrow. The scope was granted for one service point or one interval resolution, and the data you need for billing history or a second meter sits outside it. Re-authorization means going back to the customer.
• Account churn. Tenants move, buildings change hands, and service points get retired. The authorization stays valid while the underlying account stops producing data.
• Per utility variation. Token lifetimes, rotation behaviour, scope strings and error responses differ between utilities even inside the same standard, so the retry logic that works for one is not automatically right for the next.

None of these are reasons to avoid Connect My Data. They are the reasons that the maintenance cost of a CMD integration is mostly operational rather than developmental, and why it keeps costing after launch.

Build the OAuth flow yourself, or connect once

If you are weighing whether to implement CMD directly against connecting through an aggregator, the question is not whether you can write an OAuth client. You can. The question is who carries the per utility variation and the ongoing authorization monitoring.

Building it yourself is the right answer when you work with one or two utilities and need deep control of the flow. It gets harder to justify the moment a customer asks for a building served by a utility you have not integrated yet. That trade off is worked through in more detail in utility data aggregator or build your own utility integrations, and the utilities we already cover are listed on supported utilities.

Revocation and ending access

Consent is not permanent. Either the customer or the utility can revoke authorization, and when that happens the associated refresh token should be invalidated so no further access tokens can be issued. Well behaved Third Party software also stops calling the API and clears stored tokens when it learns a grant has ended. Designing for revocation from the start avoids stale connections and reflects the customer's right to turn off sharing at any time.

Why this matters in Ontario

In Ontario, Connect My Data is not optional for larger utilities. Ontario Regulation 633/21, made under the Electricity Act, 1998, requires distributors to offer both Download My Data and Connect My Data based on the NAESB ESPI standard, with the Green Button Alliance certifying those implementations. That means the OAuth flow described here is the front door to a growing set of Ontario utility data.

How EZGB manages the OAuth flow

EZGB (Easy Green Button Connector) handles the CMD authorization and token lifecycle so your team does not rebuild it for each utility. It manages the consent handoff, exchanges and refreshes tokens, respects the scopes a customer granted, and stops when access is revoked, then delivers the resulting data through an API or an ongoing feed. Because it does this across many utilities, you get one integration instead of a separate OAuth client per Data Custodian, and you can add Download My Data and PDF bill digitization to fill any gaps.

If you would rather not run the authorization lifecycle yourself, that is what EZGB does: one connection for your accounts, with the consent, refresh and revocation handling on our side. Pricing is per meter, and you can see the utilities we collect from before you commit to anything.

OAuth is what turns Green Button from a one time file into a living data connection. Understand the consent, scope, token, and revoke steps, and Connect My Data stops being a black box. From there, keeping a customer's energy data current is mostly a matter of handling refreshes and respecting the permissions they gave you.