Testing 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 received an email notifying you that your registration has been accepted. If you have not received this email, please log in to your Share My Data account and select "Manage Registration" to view your registration status.

It is important to complete testing within 90 days of your registration being accepted. If you are unable to complete testing within 90 days, your registration will expire and you will need to reregister.


IMPORTANT: With the exception of browser redirects during OAuth 2.0, all other requests between you and PG&E are over mutual SSL and require that you attach your client SSL certificate to your request. (This needs to be the same certificate you sent to PG&E prior to being accepted.)


API Connectivity Test


The following user types are required to complete API Connectivity Testing:


Standard User, Self Access, Energy Efficiency Finance and Community Choice Aggregator


Purpose:


The purpose of the API Connectivity Test is to ensure you are able to connect to the Share My Data APIs.


RECOMMENDED: Retrieving Client Access Token using SOAP UI
Sample steps for performing the first step of connectivity testing (retrieving a Client Access Token) using SOAP UI Tool.
Download the SOAP UI Tool (PDF, 520 KB).


As implementations may vary, this is intended only as a reference to help illustrate how API connections to PG&E should be performed over mutual (2-way) SSL.


API Connectivity Test Steps:


To get started, download PG&E's Entrust SSL Certificate by logging in to your account. Then select "Manage Registration" to retrieve your <Client_ID> and <Client_Secret>. These credentials will be displayed in the Registration Milestone Table, when your registration is accepted.


registration milestones


Use the client credentials to get a client access token:


  • Make a POST request against the TEST authorizationServerTokenEndpoint: https://api.pge.com/datacustodian/test/oauth/v2/token
  • Add parameter grant_type=client_credentials.
  • Add basic Authorization header parameter by Base64 encoding "client_ID:client_Secret." The header parameter will be in the format, below:
          Param name : Authorization
          Param value : Basic "base64encoded string"
  • The response will give you the client access token and its expiry time (example):
          <Response xmlns="https://api.pge.com/datacustodian/oauth/v2/token">
          <client_access_token>c03a9825-16f7-400a-b546-9a206ab995db</client_access_token>
          <expires_in>3600</expires_in>
          <scope>3</scope>
          <token_type>Bearer</token_type>
          </Response>

Use the client access token to call the service status API:


  • Make a GET request against this URL:
         https://api.pge.com/GreenButtonConnect/espi/1_1/resource/ReadServiceStatus
  • Pass the client access token in the authorization header in the format, below:
          Header param name = Authorization
          Value = Bearer <client access token>
  • The response should be as follows:
          <ServiceStatus xsi:schemaLocation="http://naesb.org/espi espiDerived.xsd" xmlns="http://naesb.org/espi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <currentStatus>1</currentStatus>
          </ServiceStatus>

Use the client access token to request the sample data:


  • Make a GET request against this URL:
          https://api.pge.com/GreenButtonConnect/espi/1_1/resource/DownloadSampleData
  • Pass the client access token in the authorization header in the format, below:
          Header param name = Authorization
          Value = Bearer <client access token>
  • The response should be as follows: Download Meter Reading Example (XML, 273 KB)

    You will have completed API Connectivity Test once you have successfully received the sample data and you will see an "API Connectivity Test: Completed" milestone in the Registration milestone table as shown below.


registration milestones 2


OAuth Test


The following users are required to complete OAuth Testing:


Standard User and Energy Efficiency Finance


Purpose:


The purpose of the OAuth Test is to ensure your OAuth implementation works correctly.


Please Note:


For the purposes of this test, your application will need to be pointed to the following endpoints in order to request the "test authorization code" and the "test access token":


  • TEST authorizationServerAuthorizationEndpoint: https://api.pge.com/datacustodian/test/oauth/v2/authorize
  • TEST authorizationServerTokenEndpoint: https://api.pge.com/datacustodian/test/oauth/v2/token

OAuth Test Directions:


  • Log-in to the Share My Data Third-Party Portal
  • Click "Go>" in the OAuth Test box
  • The OAuth Test will open in a new window. Note that if it does not open please ensure you have pop-up blocker turned off or disabled.
  • Select START: By selecting START you will be initiating the OAuth Test and correct implementation will follow the following sequence of redirects.

    ShareMyData OAuth Test:

    Issues a 302 redirect to the OAuth URL (ThirdPartyPortalURI) that you provided during Registration, with dummy scope parameters:
    Example: {ThirdPartyPortalURI}?scope=xxx&ThirdPartyID={dataCustodianId}

    Your Application:

    Optional: Your Application: Prompts (the customer) to login to your application's website

    Your Application:

    Issues a 302 redirect to the <TEST authorizationServerAuthorizationEndpoint> and makes a GET request for the Authorization Code:

    Example, use this link for TESTING ONLY:

    GET https://api.pge.com/datacustodian/test/oauth/v2/authorize?client_id={clientID value in RegistrationMilestones}&redirect_uri={redirect_uri}&scope={scope}&response_type=code

    Example, use this link for PRODUCTION ONLY:

    GET https://sharemydata.pge.com/myAuthorization?client_id={clientID value in RegistrationMilestones}&redirect_uri={redirect_uri}&response_type=code&state={optionalState}

    ShareMyDataOAuth Test:

    Issues a 302 redirect to the <Redirect URI> that you provided during Registration with the dummy Authorization Code:

    Example: https://thirdparty.com/redirectUrl?authorization_code=7afc7c4f-778a-4ad8-8337-5e19218a2219

    Your Application: Make a POST Request for the Access Token by using the Authorization Code received and calling the <TEST authorizationServerTokenEndpoint>:

    Note: for the Access Token request you must attach your SSL Certificate.
    Example:

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

    Add basic Authorization header parameter by Base64 encoding "client_ID:client_Secret"

    The header parameter will be in the following format:
    • Param name : Authorization
    • Param value : Basic "base64encoded string"

    ShareMyData OAuth Test: Responds with a test Access Token:

    A successful response will look like this:
    "access_token":" 774ff105-7ad5-40c8-a6ec-f60675dc0e41"
    "expires_in":"3600"
    "refresh_token":998c6654-5b3b-4385-af4f-4e5c46c1bb04
    "scope":"{ScopeString}"
    "resourceURI":"{ResourceURI}"
    "authorizationURI":"{AuthorizationURI}"
    "token_type":"bearer"

At this point, you will have successfully completed the OAuth Test and you will see an "OAuth Test: Completed" milestone in the Registration milestone table as shown below:


registration milestones


IMPORTANT: Upon completing testing, you must repoint your application to the Production Endpoints for Authorization Code and Access Token Request in order for customers to authorize you access to their data. These endpoints will be provided to you in the Application Information Resource (see below).


Application Information Resource Request


The following user types are required to make the Application Information Resource Request:


Standard User and Energy Efficiency Finance


Purpose:


The purpose of the Application Information Resource Request is to ensure you receive the production URLs for authorizationServerEndpoint and authorizationServerTokenEndpoint along with the dataCustodianScopeSelectionScreenURI


Application Information Resource Request Steps:


You will need your Registration Access Token and Application Information ID to request the Application information Resource.


Retrieve Registration Access Token


To retrieve your Registration Access Token log in to your Share My Data account and select "Manage Registration." Your <Registration Access Token> will be displayed in the Registration Milestone table when your registration is accepted.


registration milestones


Retrieve Application Information ID


Use the client access token retrieved during API Connectivity Test to call the Authorization xml:
Make a GET request against this URL:
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization


Pass the client access token in the authorization header in the format, below:
Header param name = Authorization
Value = Bearer <client access token>
In the response you will see the Application Information ID:


registration milestones


Request the Application Information Resource


Call the Application Information endpoint with GET to the following url: https://api.pge.com/GreenButtonConnect/espi/1_1/resource/ApplicationInformation/{ApplicationInformationID}.
Substitute {ApplicationInformationID} with the application information ID you retrieved
Add basic Authorization header parameter. The header parameter will be in the format, below:


Param name : Authorization
Param value : Bearer <registration_access_token>
The response will give you the application information resource


IMPORTANT: For instructions on how to complete the signature, please review the Green Button Implementation Agreement.


The Application Information Resource will include the following information:


  • dataCustodianId
  • dataCustodianApplicationStatus
  • thirdPartyApplicationDescription
  • thirdPartyApplicationType
  • thirdPartyPhone
  • authorizationServerUri
  • thirdPartyNotifyUri
  • authorizationServerAuthorizationEndpoint
  • authorizationServerTokenEndpoint
  • dataCustodianBulkRequestURI
  • dataCustodianResourceEndpoint
  • thirdPartyScopeSelectionScreenURI
  • thirdPartyUserPortalScreenURI
  • client_secret
  • client_name
  • redirect_uri
  • client_id
  • software_id
  • software_version
  • client_id_issued_at
  • client_secret_expires_at
  • contacts
  • token_endpoint_auth_method
  • scope
  • grant_types
  • grant_types
  • grant_types
  • response_types
  • registration_client_uri
  • registration_access_token
  • dataCustodianScopeSelectionScreenURI

If you are a Standard User or Energy Efficiency Finance user, this is the last of the three testing requirements, and, after review, your Registration will be moved to Approved as shown below. With an Approved Registration customers can now authorize you to access their data via their My Energy account, or via redirect thru your website using the <datacustodianscopeselectionURI> provided to you in the Application Information Resource Request.


IMPORTANT: You must repoint your application to the Production Endpoints for Authorization Code and Access Token Request in order for customers to authorize you access to their data. These endpoints are provided to you in the Application Information Resource.


registration milestones


Next Step: Customer Authorization


To learn more about how customers grant third parties access to their data visit Authorization Details


Once you have received customer authorization, you may begin utilizing our APIs to access the authorized data. For more information, visit Data Access

general info

Need more information? Contact us

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