Transcription
Phase 2 Online Customer Authorization (detailed): 3rd Party Initiated3rd PartyData Custodian PG&E If applicable,partner 3rd partyalso shown hereCustomerAuthenticates?YesNo(cancels)Web PortalCustomer ReviewsPre-Selected 3rdParty, SAs, Scope,Dates, T&CsAgrees h/v2/tokenWeb Services: Primary & Standalone 3RD Party TypesRequest params validated. Errors per 11) client id or redirect uri invalid or missing 400 error shown to customer2) response type missing/invalid redirectback w/ “invalid request” error3) MinAuthEndDate/PreferredAuthEndDateinvalid redirect back w/ “invalid request”error1) Error parameter as per OAuth 2.0Standard: 12) Optional State parameter also returned ifprovided as part of original request3rd Party recieves“Access Denied”error parameterRe-Direct to 3rd Party WebsiteNo(cancels)YesRe-Direct to 3rd Party WebsitePG&E IssuesAuthorization CodePG&E ValidatesAuthorization CodeReAuthorization?YesCustomer visit 3rdParty Site and wantsto share Utility DataRedirect to PG&EPG&E CustomerLogin pageAuth CodeReceive Auth Codefor Authorization w/authorized scopeparameterAuth CodeRequest AccessToken using AuthCode (via SSL)PG&E cancels oldSubscription ID &Access TokenSee Cust.AuthRevocationRedirect to authorizationServerAuthorizationEndpoint URI withrequest params: ent id xxxxxx.&redirect uri {redirect uri}&scope MinAuthEndDate XXX;PreferredAuthEndDate XXX&response type code&state {optionalState}&login {guest}-- Mandatory params in blueMin/PreferredAuthEndDate 64 bitsigned Integer in epoch seconds.-- R24 Click Thru Phase 3:client id refers to 32 characterclient id assigned during 3rd PartySMD registration (see milestones)Request header parametershould include 32 characterclientID:clientSecret from SMDregistration milestones withBase64 encoding applied.Also provide auth code (fr. priorstep) along w/ redirect uriToken Response contains:1) SubscriptionID* as part of theresourceURI parameter2)RetailCustomerID SubscriptionID AuthorizationID(same value)3) AuthorizationID as part of theauthorizationURI parameterNote: IDs to be used inconstructing customer data APIURI Endpoints4) (authorized) scopeOptional: 3rd Party HTTP GET atAuthorization API: https://api.pge.com/GreenButtonConnect/espi/1 1/resource/Authorization/{AuthorizationID}NoWeb Services: Secondary 3rdParty TypesPG&E Issues newAccess Token;Updates ClientAccess TokenDual YesAuth?AccessToken3rd Party ReceivesAccess TokenPG&E ValidatesAccess TokenClientAccessTokenOptional: 3rd PartyRequests AuthDetailsPG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives AuthDetailsPG&E Updates 2ndary3rd Party ClientAccess TokenNotification:Authorization URLReceives new AuthnotificationNoEndPG&E ValidatesAccess TokenClientAccessToken3rd Party RequestsAuth Details(Authorization URL)PG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives AuthDetails*Note: As a customer web account can have multiple Service Agreementsassociated to it, an online authorization may result in one Subscription ID mappingto multiple authorized Service Agreements (i.e. ‘Usage Points’).PG&E HTTP POST to 3rd Partyregistered Notification URL w/following payload (URL forAuthorization details API):./espi/1 1/resource/Authorization/{AuthorizationID}3rd Party HTTP GET atAuthorization API URL: ./espi/1 ation API Responsecontains:1) SubscriptionID as part of theresourceURI parameter2) RetailCustomerID SubscriptionID AuthorizationID(same value)Note: IDs to be used in constructingAPI URI Endpoints (see DataAccess)3) AuthorizedPeriod (authorizationstart & duration) 3RD Partyregistration selection. Note, as perESPI standard, indefiniteauthorizations are expressed asduration 04) PublishedPeriod (start & duration) Total window ofdata that can be requested goingback to publishedPeriod/start.5) Status: 1 active authorization; 0 revoked authorization6) (authorized) scope
AUTHORIZATION INITIATED AT THIRD-PARTY SITE(High Level Overview)Customer(browser)YourApplicationStart at Third Party (e.g. Log In)Authorization Code Request:302 est Parameters*ShareMy DataCustomer selects Utility(PG&E Data Custodian)Customer logs in, reviews/selectsScope (e.g. Service IDs, AuthorizedDate Range) & hits SUBMITAuthorization Code Request:302 est ParametersAuthorization Code & Scope Response:302 {redirect uri}?authorization code&scopeAuthorization Code & Scope Response:302 {redirect uri}?authorization code&scopeRequest Access t}?Request Parameters&authorization codeAccess Token & Scope ResponseReceipt (Authorization Successful)Use Token to call Data APIsData API responseServices/Results using DataDialog with CustomerOptional Dialog with Customer*R24 Click Thru Ph3 enhancement allows defaulting to guest access tab on customer authentication page by redirecting with the followingrequest parameter appended to redirect URL: “login guest”. All other values (e.g. no login parameter or login blank) will default to MyAccountsign-in tab. For example: nt id XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&response type code&redirect uri https://thirdpartyredirect.com&login guest
AUTHORIZATION INITIATED AT PG&E(High Level Overview)Customer(browser)YourApplicationShareMy DataCustomer discovers/selects 3rdParty from list of registered 3rdParties, hits NEXTLog in (PG&E web account)Send customer to Third Party302 {ThirdPartyPortalURI}?client id {client id}&ref {Originating PG&E URL}Optional Third Party Log InAuthorization Code Request:302 est Parameters*Authorization Code Request:302 est ParametersIf customer has logged in recently,no need to log in againCustomer reviews/selects Scope(e.g. Service IDs, Authorized DateRange) & hits SUBMITAuthorization Code & Scope Response:302 {redirect uri}?authorization code&scopeAuthorization Code & Scope Response:302 {redirect uri}?authorization code&scopeRequest Access t}?Request Parameters&authorization codeAccess Token & Scope ResponseReceipt (Authorization Successful)Use Token to call Data APIsData API responseServices/Results using DataDialog with CustomerOptional Dialog with Customer*R24 Click Thru Ph3 enhancement allows defaulting to guest access tab on customer authentication page by redirecting with the followingrequest parameter appended to redirect URL: “login guest”. All other values (e.g. no login parameter or login blank) will default to MyAccountsign-in tab. For example: nt id XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&response type code&redirect uri https://thirdpartyredirect.com&login guest
*Prior to below API requests, 3Pmust first request new ClientAccess Token using clientcredentials.Expiration Periods:Offline Customer Authorization:(PGE API URL Prefix: https://api.pge.com/GreenButtonConnect.)3rd PartyWeb Services: Secondary 3rd PartyWeb Services: Primary 3rd PartyWeb Services: Standalone 3rdPartyCISRProcessingData Custodian PG&E PG&E processesCISR formDualAuth?NPG&E UpdatesStandalone 3rd PartyClient Access Tokento include new authCISR FormNotification:Authorization URLCustomer signs 3rdParty CISR to shareUtility DataReceives new AuthnotificationPG&E ValidatesClient Access TokenClientAccessToken3rd Party RequestsAuth Details(Authorization URL)PG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives AuthDetailsYPG&E UpdatesPrimary 3rd PartyClient Access Tokento include new authNotification:Authorization URLReceives new AuthnotificationPG&E ValidatesClient Access TokenClientAccessToken3rd Party RequestsAuth Details(Authorization URL)PG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives AuthDetailsPG&E UpdatesSecondary 3rd PartyClient Access Tokento include new authNotification:Authorization URL- Client Access Token: 1hr*API Request Params are in{}PG&E HTTP POST to 3rd Partyregistered Notification URL w/following payload (URL forAuthorization details API):./espi/1 1/resource/Authorization/{AuthorizationID}3rd Party HTTP GET atAuthorization API: ./espi/1 ation API Responsecontains:1) SubscriptionID as part of theresourceURI parameter2) RetailCustomerID SubscriptionID AuthorizationID(same value)Note: IDs to be used inconstructing API URI Endpoints(see Data Access)3) AuthorizedPeriod(authorization start & duration) 3RD Party registration selection.Note, as per ESPI standard,indefinite authorizations areexpressed as duration 04) PublishedPeriod (start & duration) Total window ofdata that can be requested goingback to publishedPeriod/start.5) Status: 1 activeauthorization; 0 revokedauthorization6) (authorized) scopeIf FB 40 included indicates offlineauthorizationSee OfflineTokenCreationReceives new AuthnotificationSame as above (forstandalone 3rd Party)Same as aboverdPG&E ValidatesClient Access TokenPG&E ReturnsAuthorization/Subscription DetailsClientAccessTokenAuthorization Scope3 Party RequestsAuth Details(Authorization URL)Receives AuthDetailsSame as aboveSame as aboveSame as aboveSame as above
*Prior to below API requests, 3Pmust first request new ClientAccess Token using clientcredentialsExpiration Periods:Offline Token Creation: Offline CISR-DRP forms only(PGE API URL Prefix: https://api.pge.com/GreenButtonConnect.)3rd PartyCISRProcessingData Custodian PG&E PG&E processesCISR formWeb Services: 3rd PartyPG&E Updates 3rdParty Client AccessToken to include newauthCISR FormNotification:Authorization URLCustomer signs 3rdParty CISR to shareUtility DataReceives new AuthnotificationPG&E ValidatesClient Access TokenClientAccessToken3rd Party RequestsAuth Details(Authorization URL)PG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives /v2/token?grant type client credentials&scope {subscription id}3rd Party confirms anew offline Auth (e.g.FB 40 & authorizationstart today)PG&E ValidatesAuthorization CodeClientCredentialsPG&E Issues newAccess Token/Refresh TokenAccessTokenRequest AccessToken usingClient Credentials(via SSL)3rd Party ReceivesAccess Token- Client Access Token: 1hr*API Request Params are in{}PG&E HTTP POST to 3rd Partyregistered Notification URL w/following payload (URL forAuthorization details API):./espi/1 1/resource/Authorization/{AuthorizationID}3rd Party HTTP GET atAuthorization API: ./espi/1 ation API Responsecontains:1) SubscriptionID as part of theresourceURI parameter2) RetailCustomerID SubscriptionID AuthorizationID(same value)Note: IDs to be used inconstructing API URI Endpoints(see Data Access)3) AuthorizedPeriod(authorization start & duration) 3RD Party registration selection.Note, as per ESPI standard,indefinite authorizations areexpressed as duration 04) PublishedPeriod (start & duration) Total windowof data that can be requestedgoing back to publishedPeriod/start.5) Status: 1 activeauthorization; 0 revokedauthorization6) (authorized) scopeIf FB 40 included indicatesoffline authorizationRequest header parametershould include 32 characterclientID:clientSecret from SMDregistration milestones withBase64 encoding applied.Token Response contains:1) SubscriptionID* as part of theresourceURI parameter2)RetailCustomerID SubscriptionID AuthorizationID(same value)3) AuthorizationID as part of theauthorizationURI parameterNote: IDs to be used inconstructing customer data APIURI Endpoints4) (authorized) scope
API Data Access*(PGE API URL Prefix: https://api.pge.com/GreenButtonConnect.)3RD PartySynchronous(non-PII: 1 SA / PII: 1 Customer)AccessTokenAd-Hoc Request forlist of Usage Pointsusing Access tokenPG&E Returns list ofUsage PointsESPIformatteddataReceive list of UsagePoint IDs (obfuscatedSA IDs)PG&E ValidatesAccess TokenAccessTokenAd-Hoc Requestusing Access tokenPG&E Returns DataAssociated to AccessTokenESPIformatteddataReceive DataAssociated to AccessTokenPG&E ValidatesClient Access Token.Responds w/ 202AccessTokenAd-Hoc RequestUsing token Data Packaged &Assigned CorrelationID/URI (s)Data Ready:Notification(s)Receive CorrelationID/URI (s)PG&E ValidatesAccess TokenPG&E Validate token PG&E Returns DataAssociated toCorrelation ID- Access Token/Client Access Token:1hr- Refresh Token: 1Yr*API Request Params are in{}3rd Party GET at: ./espi/1 tExample: 3rd Party GET at:Usage & Billing Info:./espi/1 gePoint/{UsagePointID}Customer Info:./espi/1 DR Enrollment Info:./espi/1 }Example: 3rd Party GET at:Usage & Billing Info:./espi/1 ple: PG&E POST to 3rdParty registered Notification Urlw/ following payload:./espi/1 rrelationID}Request Data Using token CorrelationIDAccessTokenESPIformatteddataReceive DataAssociated toCorrelation IDExample: 3rd Party GET at:./espi/1 rrelationID}Contains latest day’sdata deltas for pastdates for all authsAsynchronous: Daily BulkSubscription (All SAs)Asynchronous Web ServicesAsynchronous(Multiple SAs)Synchronous Web ServicesData Custodian PG&E *Prior to all data request, 3P mustfirst request either new Access Refresh Token pair or new ClientAccess Token using Refresh Token/Client Credentials.Expiration Periods:Data Package(s)Assigned CorrelationID/URI (s)Data Ready:Notification(s)Receive CorrelationID/URI (s)PG&E ValidatesClient Access TokenClientAccessTokenRequest Data UsingClient Access Token Correlation ID (within 5days)PG&E Returns DataAssociated toCorrelation IDESPIformatteddataReceive DataAssociated toCorrelation ID*Note: For subsequent requests of on-going data, PG&E strongly advises using asynchronous API requestswhere possible. PG&E’s SMD/Green Button Connect platform is a free service supporting millions of customersand hundreds of 3rd parties. Malicious or unintentional redundant API requests (especially syncrhonous) canpotentially impact the ‘click through’ experience for new customer authorizations, may be throttled, and/orreported to appropriate regulatory bodies for abuse as necessary.Example: PG&E POST to 3rdParty registered Notification Urlw/ following payload:Usage & Billing Info:./espi/1 omer Info:./espi/1 CorrelationID}DR Enrollment Info:./espi/1 relationID}Example: 3rd Party GET at: /espi/1 1/resource/Batch/Bulk/{BulkID}/{CorrelationID}
Legacy API Data Access – Offline Auths & Secondary 3Ps*(PGE API URL Prefix: https://api.pge.com/GreenButtonConnect.)*To eventually be retired in a future communicated release (see offline Token Creation mechanism)3RD PartySynchronousAsynchronous Web ServicesAsynchronous(Multiple SAs)Synchronous Web ServicesData Custodian PG&E PG&E ValidatesAccess TokenClientAccessTokenAd-Hoc Requestusing Access tokenPG&E Returns DataAssociated to AccessTokenESPIformatteddataReceive DataAssociated to AccessTokenPG&E ValidatesClient Access Token.Responds w/ 202ClientAccessTokenAd-Hoc RequestUsing token Data Packaged &Assigned CorrelationID/URI (s)Data Ready:Notification(s)Receive CorrelationID/URI (s)PG&E Validate token ClientAccessTokenPG&E Returns DataAssociated toCorrelation IDESPIformatteddataRequest Data Using token CorrelationID (within 1 hour)Receive DataAssociated toCorrelation IDAsynchronous: Daily BulkSubscription (All SAs)Contains latest day’sdata deltas for pastdates for all authsData Package(s)Assigned CorrelationID/URI (s)Data Ready:Notification(s)Receive CorrelationID/URI (s)PG&E ValidatesClient Access TokenClientAccessTokenRequest Data UsingClient Access Token Correlation ID (within 5days)PG&E Returns DataAssociated toCorrelation IDESPIformatteddataReceive DataAssociated toCorrelation ID*Note: For subsequent requests of on-going data, PG&E strongly advises using asynchronous API requestswhere possible. PG&E’s SMD/Green Button Connect platform is a free service supporting millions of customersand hundreds of 3rd parties. Malicious or unintentional redundant API requests (especially synchronous) canpotentially impact the ‘click through’ experience for new customer authorizations, may be throttled, and/orreported to appropriate regulatory bodies for abuse as necessary.*Prior to all data request, 3Pmust first request either newAccess Refresh Token pairor new Client Access Tokenusing Refresh Token/ClientCredentials.Expiration Periods:- Access Token/Client AccessToken: 1hr- Refresh Token: 1Yr*API Request Params are in{}Example: 3rd Party GET at:List of Usage Pts: espi/1 agePointCustomer Info:./espi/1 omerID}DR Enrollment Info:./espi/1 tomerID}Example: 3rd Party GET at:Usage & Billing Info:./espi/1 ID}Example: PG&E POST to 3rdParty registered NotificationUrl w/ following payload:./espi/1 ID}/{CorrelationID}Example: 3rd Party GET at:./espi/1 ID}/{CorrelationID}Example: PG&E POST to 3rdParty registered NotificationUrl w/ following payload:Usage & Billing Info:./espi/1 omer Info:./espi/1 CorrelationID}DR Enrollment Info:./espi/1 1/resource/Batch/BulkRetailDRPrgInfo/{BulkID} /{CorrelationID}Example: 3rd Party GET at: /espi/1 1/resource/Batch/Bulk/{BulkID}/{CorrelationID}
API Authorization Revocation by 3Ps*(PGE API URL Prefix: https://api.pge.com/GreenButtonConnect.)3RD PartyData Custodian PG&E *Prior to below API requests,3P must first request newClient Access Token usingclient credentialsExpiration Periods:- Client Access Token: 1hrPG&E ValidatesAccess TokenSynchronousInitiating 3P: Standalone 3P orPrimary/Secondary 3P*API Request Params are in{}Ad-Hoc Requestusing Access tokenExample: 3rd Party DELETE at: /espi/1 1/resource/Authorization/{AuthorizationID}PG&E RevokesAuthorizationPG&E Updates 3rdParty Tokens toreflect revoked authDualAuth?NPG&E HTTP POST to 3rd Partyregistered Notification URL w/following payload (URL forAuthorization details API):./espi/1 ner 3PClientAccessTokenPG&E Updates other3rd Party’s Tokens toreflect revoked authNotification:Authorization URLReceives new AuthnotificationPG&E ValidatesClient Access TokenClientAccessToken3rd Party RequestsAuth Details(Authorization URL)PG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives AuthDetails3rd Party HTTP GET atAuthorization API: ./espi/1 ation API Responsecontains:1) SubscriptionID as part of theresourceURI parameter2) RetailCustomerID SubscriptionID AuthorizationID (same value)Note: IDs to be used inconstructing API URI Endpoints(see Data Access)3) AuthorizedPeriod(authorization start & duration)Note, for authorizationrevocations, theauthorizedPeriod start duration 12AM day of the revocation4) PublishedPeriod:Total window of data that canbe requested. If authorizationis revoked, value will reflectpreviously accessible window.5) Status: 1 activeauthorization; 0 revokedauthorization6) (authorized) scope
Customer Initiated Revocations/Changes w/ PG&E:(PGE API URL Prefix: https://api.pge.com/GreenButtonConnect.)rdWeb Services: Secondary 3rd PartyWeb Services: Primary 3rd PartyWeb Services: Standalone 3rdPartyCISR ProcessingData Custodian PG&E 3 PartyCustomer revokesor changes existingauthorization3rd Party HTTP GET atAuthorization API: ./espi/1 1/resource/Authorization/{AuthorizationID}PG&E processesrevocationDualAuth?NPG&E UpdatesStandalone 3rd PartyTokens to reflectrevoked authNotification:Authorization URLReceives new AuthnotificationPG&E ValidatesClient Access TokenClientAccessToken3rd Party RequestsAuth Details(Authorization URL)PG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives AuthDetailsYPG&E UpdatesPrimary 3rd PartyTokens to reflectrevoked authPG&E HTTP POST to 3rd Partyregistered Notification URL w/following payload (URL forAuthorization details API):./espi/1 tion:Authorization URLReceives new AuthnotificationPG&E ValidatesClient Access TokenClientAccessToken3rd Party RequestsAuth Details(Authorization URL)PG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives AuthDetailsAuthorization API Responsecontains:1) SubscriptionID as part of theresourceURI parameter2) RetailCustomerID SubscriptionID AuthorizationID (same value)Note: IDs to be used inconstructing API URI Endpoints(see Data Access)3) AuthorizedPeriod(authorization start & duration)Note, for authorizationrevocations, theauthorizedPeriod start duration 12AM day of the revocation4) PublishedPeriod:Total window of data that canbe requested. If authorizationis revoked, value will reflectpreviously accessible window.5) Status: 1 activeauthorization; 0 revokedauthorization6) (authorized) scopeSame as aboveSame as aboveSee APIDataAccessPG&E UpdatesSecondary 3rd PartyTokens to reflectrevoked authNotification:Authorization URLReceives new AuthnotificationPG&E ValidatesClient Access TokenClientAccessToken3rd Party RequestsAuth Details(Authorization URL)PG&E ReturnsAuthorization/Subscription DetailsAuthorization ScopeReceives AuthDetailsNote: This notification mechanism is used for notifying 3rd parties of customer initiatedauthorization changes (extending auth end date etc.) and cancellations done on PG&Eside regardless of whether the changes is for an online or offline authorization andregardless of 3rd party type (Primary/Secondary/Standalone).Same as aboveSame as aboveSame as aboveSame as above
Access Token *Note: As a customer web account can have multiple Service Agreements . Receive Data Associated to Access Token s (n-I: 1 SA / I: 1 r) Ad-Hoc Request Using token Access Token .
