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.
    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

The OAuth URL you provide here will be used to direct customers to your customer login page to complete the authorization.
(referred to as <ThirdPartyScopeSelectionScreenURL> in the ESPI ApplicationInformation Resource)

Third-Party Portal URI

This field is an information only URI and will not be used in the OAuth process. For example you can provide the URL for your Homepage or About Us page, and we may use it in the future to direct customers who want to know about your services.
(referred to as <thirdPartyUserPortalScreenURI> in the ESPI ApplicationInformation Resource)

Redirect URI

The redirect URI you provide here is where PG&E will send the Authorization Code once customer authorization is completed and you make a request for the authorization code.
(referred to as <redirect_uri> in the ESPI ApplicationInformation Resource)

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 protocol for authorizing the access of data. The diagram below illustrates how customers initiate authorization, choose scope parameters and then submit their authorization.

For detailed instructions on how third parties should implement OAuth 2.0 per ESPI guidelines, please use the following resources:

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: Community Choice Aggregators only need the <client_access_token> to request data (2-Legged OAuth).



Authorization Initiated at Third-Party Site

Authorization Initiated at PG&E's My Energy Site

Steps

1OF 2

Requesting an authorization code

After a customer has logged in to their My Energy account, selected the scope, and submitted their authorization, you will be able to request an authorization code. In order to obtain an authorization code, once the user lands on the <thirdpartyScopeSelectionURI>, you need to issue a 302 redirect to the user's browser redirecting them to the below endpoint with the parameters as mentioned below.

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

  • ?response_type=code
  • &client_id=<client_ID>
  • &redirect_uri=<redirect URL that you specified on the registration screen>
  • &scope=<scope you received from PG&E as part of the redirect to third party scope selection url (OAuth URL specified in the registration)>
  • &state=<option param to prevent browser reissues/ currently not used by PG&E>

EXAMPLE: Auth code request
GET: https://api.pge.com/datacustodian/oauth/v2/authorize?client_id={clientID}&redirect_uri={redirect_uri}&scope={scope}&response_type=code

If you make a valid request as above, in response the user will be redirected to the redirect_uri (redirect URL as specified during registration) with the authorization code as below:
https://thirdparty.com/redirectUrl?authorization_code=7afc7c4f-778a-4ad8-8337-5e19218a2219

2OF 2

Requesting an access token

To obtain an Access Token, use the Authorization Code received and call the below endpoint with parameters as mentioned below.

authorizationServerAuthorizationEndpoint: https://api.pge.com/datacustodian/oauth/v2/token
  • ?grant_type=<authorization_code>
  • &code = <auth code received>
  • &redirect_uri = <3p 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 by Base64 encoding "clientID:clientSecret"
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>5</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>

Save the access tokens.
To request initial historical data and ongoing daily usage data, visit Data Access

How customers update authorizations

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

  • Adding Service IDs to their authorizations
  • Removing Service IDs from their authorizations
  • Changing the scope of the data being shared
  • 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 My Energy, 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

In addition to the ESPI defined authorization.xml available after a customer submits their authorization, you can also view individual authorization details by logging in to your Share My Data account and entering the for the authorization. If you no longer want to access data associated with the authorization, you can cancel the authorization. The customer will be notified that you have elected to cancel the authorization.


PLEASE NOTE: Once an authorization is canceled, 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.