Authorization details

Prerequisites


The following prerequisites must be met before you can access our APIs:


  1. You must register to use the Share My Data platform before customers can authorize you to access their data. If you have not registered, please visit Share My Data: Get Started to register and complete testing.
  2. You should have completed API Connectivity and OAuth Testing. If you have not yet completed testing, please see the testing instructions. Note: the OAuth testing steps will be updated in a future release to reflect latest OAuth 2.0 functionality described below (i.e., removal of thirdPartyScopeSelectionScreenURI).
    Visit Testing Details

OAuth 2.0 URIs


The Share My Data Platform utilizes OAuth 2.0 protocol for authorization. If the User Type you have selected requires three-legged OAuth to access data, you will need to provide valid OAuth URIs before we can accept your registration.

FieldDefinition

OAuth URL

With the Share My Data Click-Through Phase 2.0 Release in June 2018, this URL is no longer used and will be retired in a future release. Until then, any properly formed https URL can be submitted as part of registration. (This is referred to as <ThirdPartyScopeSelectionScreenURI> in the ESPI Standard.)

Third-Party Portal URI

In the case of authorizations initiated at PG&E (on the customer web portal, “Your Account”), PG&E will redirect customers to this provided URL endpoint upon customers selecting your third party name from the dropdown of registered and visible Share My Data third parties. Upon redirection to this endpoint, your application has the option to initiate an authorization code request. (This is referred to as in the ESPI standard.)

Redirect URI

The redirect URI you provide here is where PG&E will send the Authorization Code once customer authorization is completed.
(This is referred to as <redirect_uri> in both the ESPI standard and the OAuth 2.0 standard.)

Customer authorization process

In order to comply with the current North American Energy Standards Board (NAESB) Energy Service Provider Interface (ESPI) standard for authorization, PG&E has implemented OAuth 2.0 Authorization framework for authorizing the access of data. The diagram below illustrates how customers initiate authorization, choose scope parameters and then submit their authorization.


Additional reference material beyond information below:



View the Green Button Implementation Agreement

Download the ESPI OAuth 2.0 Sequence Diagram (PDF, 192 KB)

View the Green Button Data SDK at GitHub


PLEASE NOTE: For Community Choice Aggregators, only the client_access_token is needed to request data (via 2-Legged OAuth) and the following does not apply.



Authorization initiated at third-party site


Authorization Initiated at Third-Party Site

Authorization initiated at PG&E


Authorization Initiated at PG&E's My Energy Site

Steps

1OF 3

Requesting an authorization code

Authorizations Initiated at the Third Party Site


To begin an authorization from a third party site as illustrated in the first diagram above, an authorization code request is made by redirecting the customer's browser from your third party site to PG&E's AuthorizationServer Authorization Endpoint URL with appropriate request parameters as exampled below. Upon redirection, the customer will be presented a PG&E log-in page for authentication, followed by an authorization page for authorizing data access to your third party:


authorizationServerAuthorizationEndpoint URI (with request parameters) https://sharemydata.pge.com/myAuthorization?client_id=xxxxx&redirect_uri={redirect_uri}&response_type=code&state={optionalState}


  • Mandatory Request Parameters:
    • client_id = 5-digit Client ID (aka ThirdPartyID) provided at the top of your Share My Data manage registration profile page. Note: as a future improvement, we are exploring options to later consolidate this value with the other 32-character client_id from your Share My Data registration milestones (i.e. client_id/client_secret pair), however for now please mind the distinction in their use.
    • redirect_uri = redirect URL that you specified in your Share My Data registration (URLs must match). PLEASE NOTE: We recommend URL encoding be applied to the redirect_uri as per example below.
    • response_type = code (static value)
  • Optional Request Parameter(s):
    • state = optional opaque state parameter as allowed by the OAuth 2.0 standard that is returned back with the authorization code in order to help maintain state. For example, the state parameter might be used by a third party to uniquely identify customer origination and to prevent cross-site forgery.

EXAMPLE: Auth code request


GET: https://sharemydata.pge.com/myAuthorization?client_id=12345&redirect_uri=https%3A%2F%2Fthirdparty.com%2FredirectUrl&response_type=code&state=pge12advertisement


PLEASE NOTE: example redirect_uri parameter above has URL encoding applied (i.e. URL encoding of https://thirdparty.com/redirectUrl)


If you make a valid request as above, and the customer successfully authenticates and authorizes, the customer will subsequently be redirected to your redirect_uri with the authorization code, (authorized) scope parameter, and optional state parameter (if provided as part of authorization request) as exampled below:


https://thirdparty.com/redirectUrl?authorization_code=7afc7c4f-778a-4ad8-8337-5e19218a2219&scope=FB=1_3_8_13_14_18_19_31_32_35_37_ 38_39_40_4_5_10_15_16_46_47;AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment;IntervalDuration=900_3600;BlockDuration=Daily;HistoryLength={3P Registered historical length};AccountCollection={count of authorizedSAs};BR={ThirdPartyID};dataCustodianId=PGE &state=pge12advertisement


PLEASE NOTE: The Authorization Code is short-lived (expires in 600 seconds), and must be subsequently exchanged for an access token/refresh token pair so as to complete the authorization and allow on-going data access. See the next section (Section 2) for details on the Access Token/ Refresh Token request.


The (authorized) scope parameter exampled above is returned as part of responses to the Authorization Code Request, the Access Token Request, as well as the Authorization API. This scope parameter allows for communicating the final scope of customer authorization. In particular, the scope parameter includes an "AdditionalScope" value that maps to PG&E's supported customer authorization selections of data groups (e.g., "Usage", "Billing", "Basic", "Account", "Program Enrollment"). The scope parameter values are further captured per the following reference documentation: Download Supported Function Block Scope String Mapping Click Thru 2.0 (PDF, 237 KB).


Error Scenarios


Third Party Implementation Errors: If the required request parameters of client_id or redirect_uri are invalid or missing upon requesting an authorization code, the customer will be shown an explanatory message along with the standard HTTP 400 "Bad Request" error. Similarly, if the required request parameter of response_type is missing or invalid, the customer will be redirected back to your redirect_uri with the OAuth 2.0 defined "invalid_request" error parameter as well as the optional state parameter if first provided as part of the original authorization code request.


Customers Declining to Authorize: Upon a third party redirecting a customer to authorize with PG&E, a customer has the option to decline via a "cancel" button at both the log-in page and the authorization page. In such instances, the customer will be redirected back to your redirect_uri with the OAuth 2.0 defined "access_denied" error parameter appended to indicate the customer declined to authorize. In addition, the optional state parameter will be returned if first provided as part of the original authorization code request.


Authorizations Initiated at PG&E


When customers start out on PG&E's customer web portal, "Your Account," and then navigate to the Share My Data landing page, they are presented a dropdown of registered and visible third parties. As illustrated in the second diagram above, upon a customer selecting a third party from the list of registered third parties and selecting "Next,"  the customer will be redirected to the third party's registered "Third Party Portal URI," at which point customers can proceed with the third-party initiated OAuth process described in the preceding section.


Note: Some third parties have inquired about how to streamline the customer experience for this use case (i.e.,  authorizations initiated on PG&E's site) such that to the customer it appears they are taken directly to an authorization page upon selecting a third party from the dropdown. To facilitate such a customer experience, third parties can elect to set their "Third Party Portal URI" (via the Share My Data manage registration page) to an endpoint that automatically redirects the customer back to PG&E as part of an authorization code request.  Upon automatic redirect back to PG&E's authorization Server Authorization Endpoint, the customer will skip the customer login page (as they are already logged in) and will go directly to the authorization page. For some third parties who have registered prior to the Share My Data Click Thru 2.0 release in late June of 2018, this can be accomplished by simply defining the Third Party Portal URI to equal the no longer used "Third Party Scope Selection Screen" URI (field to be retired in a future release).


In contrast, some third parties may want to first engage and screen customers on their side when customers are redirected to their "Third Party Portal" URI before requesting an authorization code, so the above approach is only a suggestion.

2OF 3

Requesting an access token

To obtain an Access Token, use the Authorization Code received and call the below endpoint with request parameters as described below. As described above, the Authorization Code is short lived, expiring after 10 minutes (600 seconds), so please ensure the Access Token is promptly requested upon receipt of an Authorization Code.


authorizationServerAuthorizationEndpoint: https://api.pge.com/datacustodian/oauth/v2/token


  • Mandatory Request Parameters:
    • grant_type = authorization_code (static value)
    • code = authorization code received in response to authorization code request
    • redirect_uri = redirect URL that you specified in your Share My Data registration (URLs must match). PLEASE NOTE: As with the authorization code request, we recommend URL encoding be applied to the redirect_uri.

EXAMPLE: Access Token request
POST: https://api.pge.com/datacustodian/oauth/v2/token?grant_type=authorization_code&code={authorizationcode}&redirect_uri={redirect_uri}


Add basic Authorization header parameter with Base64 encoding applied "clientID:clientSecret"
PLEASE NOTE: The clientId:clientSecret values correspond to the 32-character values provided in your Share My Data registration milestones.
The header parameter will be in the following format:
Param name : Authorization
Param value : Basic "base64encoded string"


A successful response will look like this:
<Response xmlns="https://api.pge.com/datacustodian/oauth/v2/token">
   <access_token>774ff105-7ad5-40c8-a6ec-f60675dc0e41</access_token>
   <expires_in>3600</expires_in>
   <refresh_token>998c6654-5b3b-4385-af4f-4e5c46c1bb04</refresh_token>
<scope>scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47;AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment;IntervalDuration=900_3600;BlockDuration=Daily;HistoryLength={3P Registered historical length};AccountCollection={count of authorized SAs};BR={ThirdPartyID};dataCustodianId=PGE</scope>
   resourceURI:{ResourceURI} e.g.: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionID}
   authorizationURI:{AuthorizationURI} e.g.: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{authorizationID}
   customerResourceURI:{customerResourceURI} e.g:https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}
   <token_type>Bearer</token_type>
</Response>


PLEASE NOTE: An Access Token expires in 3600 secs (1 hour), while the corresponding Refresh Token expires in 1 year. See next section 3 for details on acquiring a new Access Token/Refresh Token pair.


Save the access and refresh token pair.
To request initial historical data and ongoing daily data, visit Data Access.

3OF 3

Requesting a new access token

As per best practice, the Access Token is a short-lived token (1 hour) while the corresponding Refresh Token is a long-lived token (1 year) that you can use to acquire a new Access Token/Refresh Token pair when the Access Token expires. To obtain a new Access Token and Refresh Token pair for existing non-expired authorizations, use the "current Refresh Token" and call the below endpoint with parameters as described below.


authorizationServerAuthorizationEndpoint: https://api.pge.com/datacustodian/oauth/v2/token ?grant_type= refresh_token&refresh_token={current_refresh_token}


EXAMPLE: Refresh Token request
POST: https://api.pge.com/datacustodian/oauth/v2/token?grant_type= refresh_token&refresh_token={current_refresh_token}


Add basic Authorization header parameter with Base64 encoding applied "clientID:clientSecret"


PLEASE NOTE: The clientId:clientSecret values correspond to the 32-character values provided in your Share My Data registration milestones.
The header parameter will be in the following format:
Param name : Authorization
Param value : Basic "base64encoded string"


A successful response will look like this:
{
"access_token": "677e6ef8-1e1a-43f0-85b8-5692fcbc72b2",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "0eef9a9f-60c6-40bb-b33f-910e322c0298",
"scope": "scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47;AdditionalScope=Usage_Billing_Basic_Account_
ProgramEnrollment;IntervalDuration=900_3600;BlockDuration=Daily;HistoryLength={3P Registered historical length};AccountCollection={count of authorized SAs};BR={ThirdPartyID};dataCustodianId=PGE",
"resourceURI": "https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/test",
"authorizationURI": "https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/test"
}


PLEASE NOTE: Similarly, the Client Access Token is a short-lived token (1 hour) while its corresponding Refresh Token is a long-lived token (1 year) that you can use to acquire a new Client Access Token/Refresh Token pair when the Client Access Token expires. To obtain a new Client Access Token/Refresh Token pair, reference the same steps described above.

How customers update authorizations


Customers will be able to update their authorizations by doing the following:


  • Removing Service IDs from their authorizations
  • Extending the end date of the authorization period
  • Canceling the authorization

PLEASE NOTE: Customers will only be able to make changes to their authorizations by logging in to their online PG&E account and following the required steps. If any of these actions are taken, we will notify you via the Notification URI that you provided during registration.


Managing your customer authorizations


There are options for managing and viewing details of your customer authorizations:


  • You can call the authorization API (http GET operation) using your client_access_token either at the 3rd party level (for details on all authorizations) at https://api.pge.com/GreenButtonConnect /espi/1_1/resource/Authorization or at the individual customer authorization level at https://api.pge.com/GreenButtonConnect /espi/1_1/resource/Authorization/{AuthorizationID}.
  • Separately, you can also view individual authorization details manually by logging in to your Share My Data account via the third party portal and entering the Subscription ID for the authorization you’re searching for.

If you no longer want to access data associated with an authorization, there are optional methods to cancel an authorization:


  • You can call the authorization revocation API (http DELETE operation) using your client_access_token at https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{AuthorizationID}.
  • Alternatively, you can manually cancel an authorization by logging in to your Share My Data account via the third party portal and entering the Subscription ID for the authorization you wish to cancel.

PLEASE NOTE: The customer will be notified that you have elected to cancel their authorization. In addition, once an authorization is cancelled, the action cannot be reversed.

general info

Need more information? Contact us

If you have questions or comments, please email our team at ShareMyData@pge.com.