Phase 1 Online Customer Authorization: 3 rd Party Initiated

Transcription

1 Web Services: Secondary 3 rd Party Types Party Types Web Portal Phase 1 Online Customer n: 3 rd Party Initiated 3 rd Party CustodianScopeSelectionS creenuri as provided in ApplicationInfo API response from SMD Reg. Testing: myn?clientid=xxxxx If applicable, partner 3 rd party also shown here custodian/oauth/v2/ Authorize custodian/ oauth/v2/token Web Services: Primary & Standalone 3 RD Dual Auth? N End Y Customer Logs Into PG&E MyAccount Customer Reviews Pre-Selected 3 rd Party, SAs, Scope, Dates, T&Cs Agrees to Authorize? Yes PG&E Issues n Code n Code PG&E Issues ; Updates s Subscription 2 ndary 3 rd Party Subscription Redirect to PG&E Re-Direct to 3 rd Party Website No Re-Direct to 3 rd Party Website Re-Direct back to PG&E Auth Code Auth Code n URL Customer visit 3 rd Party Site and wants to share Utility Data As outlined in OAuth 2.0 Error Response: html/rfc6749#section rd Party Recieves _Denied error 3 rd Party Reviews Authorized Scope, Requests Auth Code Receive Auth Code for n Request using Auth Code 3 rd Party Receives Optional: 3 rd Party Requests Auth Auth (n URL) *Note: Given that a customer web account can have multiple Service Agreements associated to it, an online authorization may result in one Subscription ID (and corresponding +Refresh token) mapping to multiple authorized Service Agreements (i.e. Usage Points as modeled in XML Schema Definition). Additional OAuth : Redirect endpoint constructed with parameters appended, including: clientid (from SMD registration milestones), redirect_uri, response_type=code. Request header parameter should include clientid:clientsecret from SMD registration milestones with Base64 encoding applied. Also provide auth code (fr. prior step) along w/ redirect_uri Response contains: 1) SubscriptionID* as part of the resourceuri parameter 2)RetailCustomerID = nid (same value) 3) nid as part of the authorizationuri parameter (see Data ) Optional: 3 rd Party HTTP GET at n API:.../espi/1_1/ resource/ {nid} PG&E HTTP POST to 3 rd Party registered Notification URL w/ following payload (URL for n details API):.../espi/1_1/resource/ {nid} 3 rd Party HTTP GET at n API: /espi/1_1/ resource/ {nid} See API Data n API Response contains: 1) SubscriptionID as part of the resourceuri parameter 2) RetailCustomerID = nid (same value) (see Data ) 3) AuthorizedPeriod (authorization start & duration) = 3 RD Party registration selection. Note, as per standard, indefinite authorizations are expressed as duration = 0 4) PublishedPeriod = (start & duration) Total window of that can be requested going back to publishedperiod/ start.

2 3 rd Party Application Data Custodian (e.g. PG&E) URL provided in Application Information, requested during Registration Testing 1. sharemy.pge.com/ myn?clientid=x xxxx Generally, nothing is shown to customer here (automatic redirect back to PG&E) R24 Click Thru Phase 1 still in scope 2. After Click Thru Phase 2, these steps are skipped URL: custodian/oauth/v2/ Authorize For future R24 Click Thru Phase 2: Customer will instead log in at this step. Auth code request (redirect) would allow passing parameters (e.g. _id, preferred/min authorization period, etc.) to be reflected in customer authorization page. custodian/oauth/v2/ token

3 Web Services: Secondary 3 rd Party Web Services: Primary 3 rd Party Web Services: Standalone 3 rd Party CISR Processing Offline Customer n: PG&E processes CISR form CISR Form 3 rd Party Customer signs 3 rd Party CISR to share Utility Data PG&E HTTP POST to 3 rd Party registered Notification URL w/ following payload (URL for n details API):.../espi/1_1/resource/ {nid} Dual Auth? Y N Standalone 3 rd Party to include new auth Subscription Primary 3 rd Party to include new auth Subscription n URL n URL Auth (n URL) Auth (n URL) 3 rd Party HTTP GET at n API:.../espi/1_1/ resource/ {nid} n API Response contains: 1) SubscriptionID as part of the resourceuri parameter 2) RetailCustomerID = nid (same value) (see Data ) 3) AuthorizedPeriod (authorization start & duration) = 3 RD Party registration selection. Note, as per standard, indefinite authorizations are expressed as duration = 0 4) PublishedPeriod = (start & duration) Total window of that can be requested going back to publishedperiod/ start. Secondary 3 rd Party to include new auth n URL See API Data Auth (n URL) Subscription

4 Web Services: All 3 rd Party Types [includes Secondary 3 rd parties] Asynchronous: Daily Bulk Subscription (All SAs) Asynchronous (Multiple SAs) Web Services: Primary & Standalone 3 RD Party Types Asynchronous (Multiple SAs) (non-pii: 1 SA / PII: 1 Customer) API Data Online Auths* (from 3 RD Party for list of Usage Points using token *Prior to all request, 3P must first request new Pair ( + Refresh or + Refresh) using Refresh. Expiration Periods: - :1hr - : 5 min - Corresponding Refresh s: 1Yr *API Request Params are in{} list of Usage Points Receive list of Usage Point IDs (obfuscated SA IDs) 3 rd Party GET at:.../espi/1_1/ resource/subscription/ UsagePoint Data <token>, responds w/ HTTP 202 status Data Packaged & (from (from using token Using <token> Subscription/ UsagePoint/{UsagePointId} resource/batch/retailcustomer/ DR Enrollment Info: RetailDRPrgInfo/ Subscription/{SubscriptionID} PG&E Validate <token> Data. Responds w/ 202 Data Packaged & PG&E Validate <token> (from <token> + Correlation ID Using <token> <token> + Correlation ID URL w/ following payload: Subscription/ Subscription/ Custom/ Subscription/{SubscriptionID} Url w/ following payload: Data Data Package(s) Data Contains latest day s + deltas for past dates for all auths + (within 5 days) *Note: For subsequent requests of on-going, PG&E strongly advises using asynchronous API requests where possible. PG&E s SMD/Green Button Connect platform is a free service supporting millions of customers and hundreds of 3 rd parties. Malicious or unintentional redundant API requests (especially syncrhonous) can potentially impact the click through experience for new customer authorizations, may be throttled, and/or reported to appropriate regulatory bodies for abuse as necessary. Example: PG&E POST to 3rd Url w/ following payload: Bulk/ {BulkID}/ resource/batch/ BulkRetailCustomerInfo/ {BulkID}/ DR Enrollment Info:.../espi/ BulkRetailDRPrgInfo/{BulkID}/ /espi/ Bulk/{BulkID}/

5 Web Services: All 3 rd Party Types [includes Secondary 3 rd parties] Asynchronous: Daily Bulk Subscription (All SAs) Asynchronous (Multiple SAs) API Data Offline Auths & Secondary 3Ps* Data. Responds w/ 202 Data Packaged & PG&E Validate <token> Data Contains latest day s + deltas for past dates for all auths 3 RD Party using token Using <token> <token> + Correlation ID (within 1 hour) *Prior to all request, 3P must first request new Pair ( + Refresh or + Refresh) using Refresh. Expiration Periods: - :1hr - : 5 min - Corresponding Refresh s: 1Yr *API Request Params are in{} List of Usage Pts: espi/1_1/ resource/subscription/custom/ UsagePoint resource/batch/custom/ RetailCustomer/ DR Enrollment Info:.../espi/ Custom/ RetailDRPrgInfo/ Custom/ Subscription/{SubscriptionID} Url w/ following payload: Data Package(s) Data + (within 5 days) Url w/ following payload: Bulk/ {BulkID}/ resource/batch/ BulkRetailCustomerInfo/ {BulkID}/ DR Enrollment Info:.../espi/ BulkRetailDRPrgInfo/ {BulkID} / /espi/ Bulk/{BulkID}/ *Note: For subsequent requests of on-going, PG&E strongly advises using asynchronous API requests where possible. PG&E s SMD/Green Button Connect platform is a free service supporting millions of customers and hundreds of 3 rd parties. Malicious or unintentional redundant API requests (especially synchronous) can potentially impact the click through experience for new customer authorizations, may be throttled, and/or reported to appropriate regulatory bodies for abuse as necessary.

6 Standalone 3P or Primary/ Secondary 3P API Data n Revocation by 3Ps* 3 RD Party using token *Prior to all request, 3P must first request new Pair ( + Refresh or + Refresh) using Refresh. Expiration Periods: - :1hr - : 5 min - Corresponding Refresh s: 1Yr *API Request Params are in{} PG&E Revokes n Example: 3 rd Party DELETE at: /espi/1_1/resource/ {nid}

7 Web Services: Secondary 3 rd Party Web Services: Primary 3 rd Party Web Services: Standalone 3 rd Party CISR Processing Customer initiated Revocations w/ PG&E: PG&E processes revocation CISR Form OR PG&E manage auth page 3 rd Party Customer revokes (cancels) existing authorization PG&E HTTP POST to 3 rd Party registered Notification URL w/ following payload (URL for n details API):.../espi/1_1/resource/ {nid} Dual Auth? Y N Standalone 3 rd Party s to reflect revoked auth Subscription Primary 3 rd Party s to reflect revoked auth Subscription n URL n URL Auth (n URL) Auth (n URL) 3 rd Party HTTP GET at n API:.../espi/1_1/ resource/ {nid} n API Response contains: 1) SubscriptionID as part of the resourceuri parameter 2) RetailCustomerID = nid (same value) (see Data ) 3) AuthorizedPeriod (authorization start & duration) Note, for customer revocations, the authorizedperiod start+duration = day of the (i.e. revocations are effective immediately) 4) PublishedPeriod: Total window of that could previously be requested prior to revocation = day of the revocation historical start date. See API Data Secondary 3 rd Party s to reflect revoked auth n URL Auth (n URL) Subscription