API Connectivity Test

Software Development Kits (SDKs)

 

To assist you in the process of development for implementation of the Share My Data platform, PG&E has developed SDKs in both Javascript and Python languages. These SDKs provide samples to help guide you through the process of development, but are not intended to provide functioning code.

 

Software Updates

 

General Requirements


You must meet the following prerequisites before you can begin testing:

  • You have submitted your online registration information and provided your SSL Certificate. If not, you will need to do so before proceeding.
    Register Now >

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


  • PLEASE NOTE: You must 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 API's.

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 and . These credentials will be displayed in the Registration Milestone Table, when your registration is accepted.

Registration Milestones

DateStatus and Information
Registration Accepted

10/30/2014

Your Registration has been accepted. You should have received an email with connectivity test instructions. You will need to complete a connectivity test before customers can authorize the release of data to you. Your registration access token is b810aa79-2756-4ebe-8e1c-a627df23f340. Your client ID is 3238354B6579. Your Client Secret is: 323835536563726574

 

Registration Email Confirmed

10/21/2014

Your email address has been confirmed and your application has been submitted to PG&E for review.

Registration Submitted

10/21/2014

You should have received an email after you submitted your online Registration. Please confirm your email address by clicking on the link in the

 

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):      c03a9825-16f7-400a-b546-9a206ab995db   3600   3   Bearer   

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



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:
View Example

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

DateStatus and Information
Registration Approved

3/26/2015

You have successfully completed your connectivity testing and are ready for the Share My Data program.

Request Completion

3/26/2015

Application Information Resource Request: Completed

Connectivity Test

3/26/2015

API Connectivity Test: Completed

Test Completion

3/26/2015

OAuth Test: Completed

Registration Accepted

3/25/2015

Your registration has been accepted. You should have received an email with test instructions. You will need to complete testing before customers can authorize the release of data to you. Your registration access token is 0259aab2-3dcb-4072-99b9-33f89a2bed75. Your Client_ID is: 33353438364B6579. Your Client_secret is : 3335343836536563726574

Registration Email Confirmed

3/25/2015

Your email address has been confirmed and your application has been submitted to PG&E for review.

Registration Submitted

3/25/2015

You should have received an email after you submitted your online Registration. Please confirm your email address by clicking on the link in the email.

OAuth Test


The following users are required to complete OAuth Test: 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 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 (thirdPartyScopeSelectionURI) that you provided during Registration, with dummy scope parameters:

          • Example: {thirdPartyScopeSelectionScreenURI}?scope=xxx&ThirdPartyID={dataCustodianId}


        • Your Application: Prompts you to log-in to your account on your application’s website

          • Optional: Your Application: Confirm scope

        • Your Application: Issues a 302 redirect to the and makes a GET request for the Authorization Code:

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


        • ShareMyDataOAuth Test: Issues a 302 redirect to the 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 : 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}


          • Param name : Authorization

          • Param value : Basic "base64encoded string"



        • Add basic Authorization header parameter by Base64 encoding "client_ID:client_Secret" The header parameter will be in the following format:

        • ShareMyData OAuth Test: Responds with a test Access Token:

          • A successful response will look like this:

            • 774ff105-7ad5-40c8-a6ec-f60675dc0e41 3600 998c6654-5b3b-4385-af4f-4e5c46c1bb04 5 resourceURI:{ResourceURI} authorizationURI:{AuthorizationURI} 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:

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

Registration Milestones

DateStatus and Information
Registration Approved

3/26/2015

You have successfully completed your connectivity testing and are ready for the Share My Data program.

Request Completion

3/26/2015

Application Information Resource Request: Completed

Connectivity Test

3/26/2015

API Connectivity Test: Completed

Test Completion

3/26/2015

OAuth Test: Completed

Registration Accepted

3/25/2015

Your registration has been accepted. You should have received an email with test instructions. You will need to complete testing before customers can authorize the release of data to you. Your registration access token is 0259aab2-3dcb-4072-99b9-33f89a2bed75. Your Client_ID is: 33353438364B6579. Your Client_secret is : 3335343836536563726574

Registration Email Confirmed

3/25/2015

Your email address has been confirmed and your application has been submitted to PG&E for review.

Registration Submitted

3/25/2015

You should have received an email after you submitted your online Registration. Please confirm your email address by clicking on the link in the email.

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 will be displayed in the Registration Milestone table when your registration is accepted.

Registration Milestones

DateStatus and Information
Registration Accepted

10/30/2014

Your Registration has been accepted. You should have received an email with connectivity test instructions. You will need to complete a connectivity test before customers can authorize the release of data to you. Your registration access token is b810aa79-2756-4ebe-8e1c-a627df23f340. Your client ID is 3238354B6579. Your Client Secret is: 323835536563726574

 

Registration Email Confirmed

10/21/2014

Your email address has been confirmed and your application has been submitted to PG&E for review.

Registration Submitted

10/21/2014

You should have received an email after you submitted your online Registration. Please confirm your email address by clicking on the link in the

 

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 In the response you will see the Application Information ID

</ns0:token_type>Bearer</ns0:token_type>
</ns0:resourceURL>https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Applicationinformation/859dfe76-c5b4-434f-bad9-4364f08784ff</ns0:resourceURL>
</ns0:authorizationURL>https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/35425</ns):authorizationURL>
</ns0:authorizationURL>


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 theGreen Button Implementation Agreement

  • 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 your Registration will automatically 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

DateStatus and Information
Registration Approved

3/26/2015

You have successfully completed your connectivity testing and are ready for the Share My Data program.

Request Completion

3/26/2015

Application Information Resource Request: Completed

Connectivity Test

3/26/2015

API Connectivity Test: Completed

Test Completion

3/26/2015

OAuth Test: Completed

Registration Accepted

3/25/2015

Your registration has been accepted. You should have received an email with test instructions. You will need to complete testing before customers can authorize the release of data to you. Your registration access token is 0259aab2-3dcb-4072-99b9-33f89a2bed75. Your Client_ID is: 33353438364B6579. Your Client_secret is : 3335343836536563726574

Registration Email Confirmed

3/25/2015

Your email address has been confirmed and your application has been submitted to PG&E for review.

Registration Submitted

3/25/2015

You should have received an email after you submitted your online Registration. Please confirm your email address by clicking on the link in the email.

Next Step: Customer Authorization


Visit the Share My Data Customer Authorization Process page to learn more about how customers grant third parties access to their data. Go to Authorization Overview >

Once you have received customer authorization, you may begin utilizing our APIs to access the authorized data. Visit the Share My Data Access & API Overview page for more information. Go to Data Access & API Overview >