The Authorization resource represents the current state of a Third Party application's ability to access Retail Customer authorized Data Custodian information. Both the Data Custodian and Third Party applications are expected to maintain the information contained within the resource structure, which should be created upon the successful completion of generation of an OAuth 2.0 access token process. The Data Custoidn must provide all required and known optional elements on demand. The Authorization resource is accessed via the Data Custodian application's Authorization API interface. This interface support is required for any Data Custodian application to obtain the Green Button Data Custodian Connect My Data (CMD) certification.
Elements of the Authorization resource that are required appear BOLD in the Element column of the following table. The Sample Content column of the table shows values defined by the North American Energy Standards Board's (NAESB) Energy Service Provider Interface (ESPI - REQ.21) standard and include current extensions as defined by the derivedESPI.XSD schema.
Element | Description | Sample Content |
---|---|---|
authorizedPeriod | Restricts access to requests or subscriptions to date time period indicated. | <authorizedPeriod>
<duration>31536000</duration> <start>133325800</start> </authorizedPeriod> |
publishedPeriod | Restricts access to the objects within the associated resource that were published within date time period indicated. | <publishedPeriod>
<duration>31536000</duration> <start>133325800</start> </publishedPeriod> |
status | The status of this authorization. Defined types are: 0 - Revoked 1 - Active 2 - Denied | <status> 1 </status> |
expires_at | Expiration period for the access_token (seconds). NOTE: OAuth returns expration number of seconds. This must be converted to an absolute time at which the access token expires. | <expires_at>1333252800</expires_at> |
grant_type | Type of OAuth 2.0 grant being negotiated Defined types are: authorization_code client_credentials refresh_token | <grant_type> authorization_code </grant_type> |
scope | Negotiated scope of the authorization Note: The OAuth 2.0 Scope Encoding section describes the format of the scope element | <scope> FB=1_3_4_5_13_14_15_19_37_39; IntervalDuration=3600; BlockDuration=monthly; HistoryLength=94608000 </scope> |
token_type | Type of OAuth 2.0 token used Defined types are: bearer | <token_type> bearer </token_type> |
error | Contains error type returned by Data Custodian during access_token negotiation if an error was returned rather than an access token | <error> invalid_client </error> |
error_description | Contains free text string describing error returned by Data Custodian during access_token negotiation if an error was returned rather than an access token | <error_description> invalid access token </error_description> |
error_uri | Contains URI of error returned by Data Custodian during access_token negotiation if an error was returned with an error_uri rather than an access token | <error_uri> NA </error_uri> |
resourceURI | URI assigned by Data Custodian used to access resource Subscription | <resourceURI> https://sandbox.greenbuttonalliance.org :8443/DataCustodian/espi/1_1/resource/ Batch/Subscription/100436 </resourceURI> |
authorizationURI | URI assigned by Data Custodian used to access this Authorization | <authorizationURI> https://sandbox.greenbuttonalliance.org: 8443/DataCustodian/espi/1_1/resource/ Authorization/101 </authorizationURI> |
retailCustomerURI | URI assigned by Data Custodian used to access RetailCustomer Personal Identifiable Information (PII) | <retailCustomerURI> https://sandbox.greenbuttonalliance.org: 8443/DataCustodian/espi/1_1/resource/ RetailCustomer/2093582 </retailCustomerURI> |