datarightplus S. Low Internet-Draft Biza.io Intended status: Experimental 1 April 2024 Expires: 3 October 2024 DataRight+: Energy Resource Set draft-authors-datarightplus-resource-set-energy-latest Abstract This is the resource set profile outlining the energy sector related endpoints. In addition to outlining Initiator and Provider provisions it also specifies requirements for the Energy Authority (electricity assets and usage) and Energy Plan Website (retail electricity plan information). Notational Conventions The keywords "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 3 October 2024. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Table of Contents 1. Scope 2. Terminology 3. Providers 3.1. Authorisation Server 3.1.1. Authorisation Scopes 3.2. Resource Server 3.2.1. Electricity Authority Resource Bridge 4. Initiators 5. Electricity Authority 5.1. Authorisation Server 5.2. Resource Server 6. Electricity Plan Website 7. Acknowledgement 8. Normative References Author's Address 1. Scope The scope of this document is intended to be limited to the resource server endpoints related to energy, their associated authorisation contexts, the services provided by the Energy Authority and Energy Plan Website. 2. Terminology This specification utilises the various terms outlined within [DATARIGHTPLUS-ROSETTA]. 3. Providers Providers which manage energy sector information are expected to deliver a number of resource server end points. 3.1. Authorisation Server In addition to other provisions incorporated within the relevant ecosystem set, the Provider authorisation server SHALL: 1. Support the [RFC6749] scope parameter with possible values outlined within Authorisation Scopes (#name-authorisation- scopes); 3.1.1. Authorisation Scopes The Provider authorisation server SHALL utilise the following Data Set Language when seeking Consumer authorisation from a User for specific scope values: +==============================================+==================+ | scope value | Data Set | | | Language | +==============================================+==================+ | energy:accounts.basic:read | *Accounts and | | | plans* | +----------------------------------------------+------------------+ | | Account and plan | | | information; | +----------------------------------------------+------------------+ | energy:accounts.detail:read | *Account and | | | plan details* | +----------------------------------------------+------------------+ | | Account type; | +----------------------------------------------+------------------+ | | Fees, features, | | | rates, and | | | discounts; | +----------------------------------------------+------------------+ | | Additional | | | account users; | +----------------------------------------------+------------------+ | energy:accounts.concessions:read | *Concessions and | | | assistance* | +----------------------------------------------+------------------+ | | Concession type; | +----------------------------------------------+------------------+ | | Concession | | | information; | +----------------------------------------------+------------------+ | energy:accounts.paymentschedule:read | *Payment | | | preferences* | +----------------------------------------------+------------------+ | | Payment and | | | billing | | | frequency; | +----------------------------------------------+------------------+ | | Any scheduled | | | payment details; | +----------------------------------------------+------------------+ | energy:billing:read | *Billing | | | payments and | | | history* | +----------------------------------------------+------------------+ | | Account balance; | +----------------------------------------------+------------------+ | | Payment method; | +----------------------------------------------+------------------+ | | Payment status; | +----------------------------------------------+------------------+ | | Charges, | | | discounts, | | | credits; | +----------------------------------------------+------------------+ | | Billing date; | +----------------------------------------------+------------------+ | | Usage for | | | billing period; | +----------------------------------------------+------------------+ | | Payment date; | +----------------------------------------------+------------------+ | | Invoice number; | +----------------------------------------------+------------------+ | energy:electricity.servicepoints.basic:read | *Electricity | | | connection* | +----------------------------------------------+------------------+ | | National Meter | | | Identifier | | | (NMI); | +----------------------------------------------+------------------+ | | Customer type; | +----------------------------------------------+------------------+ | | Connection point | | | details; | +----------------------------------------------+------------------+ | energy:electricity.servicepoints.detail:read | *Electricity | | | meter* | +----------------------------------------------+------------------+ | | Supply address; | +----------------------------------------------+------------------+ | | Meter details; | +----------------------------------------------+------------------+ | | Associated | | | service | | | providers; | +----------------------------------------------+------------------+ | energy:electricity.der:read | *Energy | | | generation and | | | storage* | +----------------------------------------------+------------------+ | | Generation | | | information; | +----------------------------------------------+------------------+ | | Generation or | | | storage device | | | type; | +----------------------------------------------+------------------+ | | Device | | | characteristics; | +----------------------------------------------+------------------+ | | Devices that can | | | operate without | | | the grid; | +----------------------------------------------+------------------+ | | Energy | | | conversion | | | information; | +----------------------------------------------+------------------+ | energy:electricity.usage:read | *Electricity | | | usage* | +----------------------------------------------+------------------+ | | Usage; | +----------------------------------------------+------------------+ | | Meter details; | +----------------------------------------------+------------------+ Table 1 3.1.1.1. Overlapping Scope Optimisation Alternative Data Cluster Language SHALL be used when pairs of scope value are used as follows: +==============================================+==================+ | scope pairing | Data Set | | | Language | +==============================================+==================+ | energy:accounts.basic:read and | *Account and | | | plan details* | +----------------------------------------------+------------------+ | energy:accounts.detail:read | Account and plan | | | information; | +----------------------------------------------+------------------+ | | Account type; | +----------------------------------------------+------------------+ | | Fees, features, | | | rates, and | | | discounts; | +----------------------------------------------+------------------+ | | Additional | | | account users; | +----------------------------------------------+------------------+ | energy:electricity.servicepoints.basic:read | *Electricity | | and | connection and | | | meter* | +----------------------------------------------+------------------+ | energy:electricity.servicepoints.detail:read | National Meter | | | Identifier | | | (NMI); | +----------------------------------------------+------------------+ | | Supply address; | +----------------------------------------------+------------------+ | | Customer type; | +----------------------------------------------+------------------+ | | Connection point | | | details; | +----------------------------------------------+------------------+ | | Meter details; | +----------------------------------------------+------------------+ | | Associated | | | service | | | providers; | +----------------------------------------------+------------------+ Table 2 3.2. Resource Server The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:accounts.basic:read scope value: +==========================+===========+ | Resource Server Endpoint | Valid x-v | +==========================+===========+ | GET /energy/accounts | 2 | +--------------------------+-----------+ Table 3 The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:accounts.detail:read scope value: +==================================+===========+ | Resource Server Endpoint | Valid x-v | +==================================+===========+ | GET /energy/accounts/{accountId} | 2, 3 | +----------------------------------+-----------+ Table 4 The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:accounts.concessions:read scope value: +==============================================+===========+ | Resource Server Endpoint | Valid x-v | +==============================================+===========+ | GET /energy/accounts/{accountId}/concessions | 1 | +----------------------------------------------+-----------+ Table 5 The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:accounts.paymentschedule:read scope value: +===================================================+===========+ | Resource Server Endpoint | Valid x-v | +===================================================+===========+ | GET /energy/accounts/{accountId}/payment-schedule | 1 | +---------------------------------------------------+-----------+ Table 6 The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:billing:read scope value: +===========================================+===========+ | Resource Server Endpoint | Valid x-v | +===========================================+===========+ | GET /energy/accounts/balances | 1 | +-------------------------------------------+-----------+ | GET /energy/accounts/{accountId}/balance | 1 | +-------------------------------------------+-----------+ | POST /banking/accounts/balances | 1 | +-------------------------------------------+-----------+ | GET /energy/accounts/{accountId}/invoices | 1 | +-------------------------------------------+-----------+ | GET /energy/accounts/invoices | 1 | +-------------------------------------------+-----------+ | POST /energy/accounts/invoices | 1 | +-------------------------------------------+-----------+ | GET /energy/accounts/{accountId}/billing | 1 | +-------------------------------------------+-----------+ | GET /energy/accounts/billing | 1 | +-------------------------------------------+-----------+ | POST /energy/accounts/billing | 1 | +-------------------------------------------+-----------+ Table 7 The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:electricity.usage:read scope value: +=========================================+===========+ | Resource Server Endpoint | Valid x-v | +=========================================+===========+ | GET /energy/electricity/ | 1 | | servicepoints/{servicePointId}/usage | | +-----------------------------------------+-----------+ | GET /energy/electricity/servicepoints/ | 1 | | usage | | +-----------------------------------------+-----------+ | POST /energy/electricity/servicepoints/ | 1 | | usage | | +-----------------------------------------+-----------+ Table 8 The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:electricity.servicepoints.basic:read scope value: +=======================================+===========+ | Resource Server Endpoint | Valid x-v | +=======================================+===========+ | GET /energy/electricity/servicepoints | 1 | +---------------------------------------+-----------+ Table 9 The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:electricity.servicepoints.detail:read scope value: +================================+===========+ | Resource Server Endpoint | Valid x-v | +================================+===========+ | GET /energy/electricity/ | 1 | | servicepoints/{servicePointId} | | +--------------------------------+-----------+ Table 10 The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:electricity.der.basic:read scope value: +============================================+===========+ | Resource Server Endpoint | Valid x-v | +============================================+===========+ | GET /energy/electricity/servicepoints/der | 1 | +--------------------------------------------+-----------+ | POST /energy/electricity/servicepoints/der | 1 | +--------------------------------------------+-----------+ Table 11 In addition, the Provider MAY deliver the following unauthenticated and generally available endpoints, in accordance with [DATARIGHTPLUS-REDOCLY-ID1]: +============================+=====+ | Resource Server Endpoint | x-v | +============================+=====+ | GET /energy/plans | 1 | +----------------------------+-----+ | GET /energy/plans/{planId} | 1 | +----------------------------+-----+ Table 12 3.2.1. Electricity Authority Resource Bridge In order to deliver information requested by the Initiator the Provider SHALL provide a back-to-back relay of resource server requests between the Provider and Electricity Authority as follows: +====================================+============================================+ |Provider Resource Server Endpoint |Electricity Authority Resource Server | | |Endpoint | +====================================+============================================+ |GET /energy/electricity/ |GET /secondary/energy/electricity/ | |servicepoints/{servicePointId}/usage|servicepoints/{servicePointId}/usage | +------------------------------------+--------------------------------------------+ |GET |GET | |/energy/electricity/servicepoints/ |/secondary/energy/electricity/servicepoints/| |usage |usage | +------------------------------------+--------------------------------------------+ |POST |POST | |/energy/electricity/servicepoints/ |/secondary/energy/electricity/servicepoints/| |usage |usage | +------------------------------------+--------------------------------------------+ |GET /energy/electricity/ |GET /secondary/energy/electricity/ | |servicepoints |servicepoints | +------------------------------------+--------------------------------------------+ |GET /energy/electricity/ |GET /secondary/energy/electricity/ | |servicepoints/{servicePointId} |servicepoints/{servicePointId} | +------------------------------------+--------------------------------------------+ |GET |GET | |/energy/electricity/servicepoints/ |/secondary/energy/electricity/servicepoints/| |der |der | +------------------------------------+--------------------------------------------+ |POST |POST | |/energy/electricity/servicepoints/ |/secondary/energy/electricity/servicepoints/| |der |der | +------------------------------------+--------------------------------------------+ Table 13 _Note:_ Refer to the Provider Resource Server (#resource-server) and Electricity Authority Resource Server (#resource-server-1) sections for the appropriate API mappings. 4. Initiators Initiators SHALL describe the requested scope values using the same Data Set Language as Providers, as outlined in Authorisation Scopes (#name-authorisation-scopes). 5. Electricity Authority The Electricity Authority SHALL deliver the electricity asset and usage information to the Provider. 5.1. Authorisation Server The Electricity Authority SHALL authorise Providers using existing information security protocols. The specific details of this are outside the scope of this document. 5.2. Resource Server The Electricity Authority SHALL make the following restricted endpoints available to Providers, using existing authentication and authorisation channels, and in accordance with [DATARIGHTPLUS-REDOCLY-ID1]: +===================================================+===========+ | Resource Server Endpoint | Valid x-v | +===================================================+===========+ | GET /secondary/energy/electricity/ | 1 | | servicepoints/{nationalMeteringId}/usage | | +---------------------------------------------------+-----------+ | POST /secondary/energy/electricity/servicepoints/ | 1 | | usage | | +---------------------------------------------------+-----------+ | POST /secondary/energy/electricity/servicepoints | 1 | +---------------------------------------------------+-----------+ | GET /secondary/energy/electricity/ | 1 | | servicepoints/{nationalMeteringId} | | +---------------------------------------------------+-----------+ | GET /secondary/energy/electricity/ | 1 | | servicepoints/{nationalMeteringId}/der | | +---------------------------------------------------+-----------+ | POST /secondary/energy/electricity/servicepoints | 1 | +---------------------------------------------------+-----------+ Table 14 6. Electricity Plan Website The Electricity Plan Website SHALL deliver the following unauthenticated and generally available endpoints, in accordance with [DATARIGHTPLUS-REDOCLY-ID1]: +============================+===========+ | Resource Server Endpoint | Valid x-v | +============================+===========+ | GET /energy/plans | 1 | +----------------------------+-----------+ | GET /energy/plans/{planId} | 1 | +----------------------------+-----------+ Table 15 7. Acknowledgement The following people contributed to this document: * Stuart Low (Biza.io) - Editor We acknowledge the contribution to the [CDS] of the following individuals: * James Bligh (Data Standards Body) - Lead Architect for the Consumer Data Right * Mark Verstege (Data Standards Body) - Lead Architect, Banking & Information Security for the Consumer Data Right * Ivan Hosgood (formerly Data Standards Body & ACCC) - Solutions Architect 8. Normative References [CDS] Data Standards Body (Treasury), "Consumer Data Standards (CDS)", . [DATARIGHTPLUS-REDOCLY-ID1] Low, S., Kolera, B., and W. Cai, "DataRight+: Redocly (ID1)", . [DATARIGHTPLUS-ROSETTA] Low, S., "DataRight+ Rosetta Stone", . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", October 2012, . Author's Address Stuart Low Biza.io Email: stuart@biza.io