Consumer Data Right (Energy) Data Holder Client Registration API

openapi: 3.2.0
info:
  contact:
    email: contact@dsb.gov.au
    name: Data Standards Body
    url: https://dsb.gov.au/
  description: Specifications for Dynamic Client Registration endpoints applicable to all data holders (except secondary data holders).
  title: CDR Dynamic Client Registration Data Holder Client Registration API
  version: 1.36.0
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- description: Data Holder Client Registration endpoints
  name: Data Holder Client Registration
  x-shortName: Client Registration
paths:
  /register:
    post:
      description: "Register a client using a CDR Register issued Software Statement Assertion. \n\nThis endpoint does not require [CORS](#cors)."
      operationId: postClientRegistration
      requestBody:
        $ref: '#/components/requestBodies/RequestClientRegistration'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationProperties'
          description: Client registration success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationError'
          description: Request failed due to client error
      summary: Register Data Recipient oAuth Client
      tags:
      - Data Holder Client Registration
  /register/{ClientId}:
    delete:
      description: Delete a Client Registration for a given Client ID.
      operationId: deleteClientRegistration
      parameters:
      - description: The client ID issued by the target Data Holder.
        explode: false
        in: path
        name: ClientId
        required: true
        schema:
          type: string
        style: simple
      - description: An Authorisation Token as per **[[RFC6750]](#nref-RFC6750)**.
        explode: false
        in: header
        name: Authorization
        required: true
        schema:
          type: string
        style: simple
        x-cds-type: ExternalRef
      responses:
        '204':
          description: Client deleted
        '401':
          description: Request failed due to unknown or invalid Client or invalid access token
          headers:
            WWW-Authenticate:
              description: The Response Header Field as per **[[RFC6750]](#nref-RFC6750)**.
              explode: false
              schema:
                type: string
              style: simple
              x-cds-type: ExternalRef
        '403':
          description: The client does not have permission to read, update or delete the Client
        '405':
          description: Method Not Allowed. The requested method is unsupported
      summary: Delete Data Recipient oAuth Client Registration
      tags:
      - Data Holder Client Registration
      x-scopes:
      - cdr:registration
    get:
      description: Get a Client Registration for a given Client ID.
      operationId: getClientRegistration
      parameters:
      - description: The client ID issued by the target Data Holder.
        explode: false
        in: path
        name: ClientId
        required: true
        schema:
          type: string
        style: simple
      - description: An Authorisation Token as per **[[RFC6750]](#nref-RFC6750)**.
        explode: false
        in: header
        name: Authorization
        required: true
        schema:
          type: string
        style: simple
        x-cds-type: ExternalRef
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationProperties'
          description: Client registration retrieval success
        '401':
          description: Request failed due to unknown or invalid Client or invalid access token
          headers:
            WWW-Authenticate:
              description: The Response Header Field as per **[[RFC6750]](#nref-RFC6750)**.
              explode: false
              schema:
                type: string
              style: simple
              x-cds-type: ExternalRef
        '403':
          description: The client does not have permission to read, update or delete the Client
      summary: Get oAuth Client Registration
      tags:
      - Data Holder Client Registration
      x-scopes:
      - cdr:registration
    put:
      description: Update a Client Registration for a given Client ID.
      operationId: putClientRegistration
      parameters:
      - description: The client ID issued by the target Data Holder.
        explode: false
        in: path
        name: ClientId
        required: true
        schema:
          type: string
        style: simple
      - description: An Authorisation Token as per **[[RFC6750]](#nref-RFC6750)**.
        explode: false
        in: header
        name: Authorization
        required: true
        schema:
          type: string
        style: simple
        x-cds-type: ExternalRef
      requestBody:
        $ref: '#/components/requestBodies/RequestClientRegistration'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationProperties'
          description: Client registration update success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationError'
          description: Request failed due to client error
        '401':
          description: Request failed due to unknown or invalid Client or invalid access token
          headers:
            WWW-Authenticate:
              description: The Response Header Field as per **[[RFC6750]](#nref-RFC6750)**.
              explode: false
              schema:
                type: string
              style: simple
              x-cds-type: ExternalRef
        '403':
          description: The client does not have permission to read, update or delete the Client
      summary: Update Data Recipient Registration
      tags:
      - Data Holder Client Registration
      x-scopes:
      - cdr:registration
components:
  schemas:
    ClientRegistrationRequestV1:
      description: The registration request JWT to be used to register with a Data Holder. The schema of the payload section of the decoded string(JWT) is defined in [ClientRegistration](#cdr-dynamic-client-registration-api_schemas_tocSclientregistration).
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      format: JWT
      type: string
    RegistrationError:
      properties:
        error:
          description: Predefined error code as described in [section 3.3 OIDC Dynamic Client Registration](https://openid.net/specs/openid-connect-registration-1_0.html).
          enum:
          - invalid_redirect_uri
          - invalid_client_metadata
          - invalid_software_statement
          - unapproved_software_statement
          type: string
        error_description:
          description: Additional text description of the error for debugging.
          type: string
          x-cds-type: ASCIIString
      required:
      - error
      type: object
    RegistrationProperties:
      properties:
        client_id:
          description: Data Holder issued client identifier string.
          example: 2cfefa98-7d4a-4bcb-95da-47063b84d410
          type: string
        client_id_issued_at:
          description: Time at which the client identifier was issued expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC.
          example: 1574398833
          type: integer
          x-cds-type: ExternalRef
        client_name:
          description: Human-readable string name of the software product to be presented to the end-user during authorization.
          example: Mock Software
          type: string
        client_description:
          description: Human-readable string name of the software product description to be presented to the end user during authorization.
          example: A mock software product
          type: string
        client_uri:
          description: URL string of a web page providing information about the client.
          example: https://adr.example.com
          type: string
          x-cds-type: URIString
        legal_entity_id:
          description: A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Legal Entity.
          example: 3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7
          type: string
        legal_entity_name:
          description: Human-readable string name of the Accredited Data Recipient Legal Entity.
          example: Mock Company Pty Ltd.
          type: string
        org_id:
          description: A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Brand.
          example: 3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8
          type: string
        org_name:
          description: Human-readable string name of the Accredited Data Recipient to be presented to the end user during authorization.
          example: Mock Company Brand
          type: string
        redirect_uris:
          description: Array of redirection URI strings for use in redirect-based flows. If used, _redirect_uris_ **MUST** match or be a subset of the _redirect_uris_ as defined in the SSA.
          example:
          - https://adr.example.com/redirects/redirect1
          - https://adr.example.com/redirects/redirect2
          items:
            type: string
            x-cds-type: URIString
          type: array
        sector_identifier_uri:
          description: URL string referencing the client sector identifier URI, used as an optional input to the Pairwise Identifier.
          example: https://adr.example.com/sector_identifier.json
          type: string
          x-cds-type: URIString
        logo_uri:
          description: URL string that references a logo for the client. If present, the server **SHOULD** display this image to the end-user during approval.
          example: https://adr.example.com/logos/logo1.png
          type: string
          x-cds-type: URIString
        tos_uri:
          description: URL string that points to a human-readable terms of service document for the Software Product.
          example: https://adr.example.com/tos.html
          type: string
          x-cds-type: URIString
        policy_uri:
          description: URL string that points to a human-readable policy document for the Software Product.
          example: https://adr.example.com/policy.html
          type: string
          x-cds-type: URIString
        jwks_uri:
          description: URL string referencing the client JSON Web Key (JWK) Set **[[RFC7517]](#nref-RFC7517)** document, which contains the client public keys.
          example: https://adr.example.com/jwks
          type: string
          x-cds-type: URIString
        revocation_uri:
          description: URI string that references the location of the Software Product consent revocation endpoint.
          example: https://adr.example.com/revocation
          type: string
          x-cds-type: URIString
        recipient_base_uri:
          description: Base URI for the Consumer Data Standard Data Recipient endpoints. This should be the base to provide reference to all other Data Recipient Endpoints.
          example: https://adr.example.com
          type: string
          x-cds-type: URIString
        token_endpoint_auth_method:
          description: The requested authentication method for the token endpoint.
          enum:
          - private_key_jwt
          type: string
        token_endpoint_auth_signing_alg:
          description: The algorithm used for signing the JWT.
          enum:
          - PS256
          - ES256
          type: string
        grant_types:
          description: Array of OAuth 2.0 grant type strings that the client can use at the token endpoint.
          example:
          - client_credentials
          - authorization_code
          - refresh_token
          items:
            enum:
            - client_credentials
            - authorization_code
            - refresh_token
            type: string
          type: array
        response_types:
          description: Array of the OAuth 2.0 _response_type_ strings that the client can use at the authorization endpoint.<br><br>_response_type_ value `code` is required for Authorization Code Flow.<br>_response_type_ value `code id_token` is required for OIDC Hybrid Flow.
          items:
            enum:
            - code
            - code id_token
            type: string
          type: array
        application_type:
          default: web
          description: Kind of the application. The only supported application type will be `web`.
          enum:
          - web
          type: string
        id_token_signed_response_alg:
          description: Algorithm with which an id_token is to be signed.
          enum:
          - PS256
          - ES256
          type: string
        id_token_encrypted_response_alg:
          description: 'JWE _alg_ algorithm with which an id_token is to be encrypted.<br/><br/>Required only if OIDC Hybrid Flow (_response_type_: `code id_token`) is registered.'
          example: RSA-OAEP
          type: string
          x-cds-type: ExternalRef
        id_token_encrypted_response_enc:
          description: 'JWE `enc` algorithm with which an id_token is to be encrypted.<br/><br/>Required only if OIDC Hybrid Flow (_response_type_: `code id_token`) is registered.'
          example: A256GCM
          type: string
          x-cds-type: ExternalRef
        authorization_signed_response_alg:
          description: The JWS _alg_ algorithm required for signing authorization responses. If this is specified, the response will be signed using JWS and the configured algorithm. The algorithm `none` is not allowed.<br><br>Required if _response_type_ of `code` is registered by the client.
          enum:
          - PS256
          - ES256
          example: PS256
          type: string
          x-conditional: true
        authorization_encrypted_response_alg:
          description: The JWE _alg_ algorithm required for encrypting authorization responses. If unspecified, the default is that no encryption is performed.<br><br>Required if _authorization_encrypted_response_enc_ is included.
          enum:
          - RSA-OAEP
          - RSA-OAEP-256
          example: RSA-OAEP
          type: string
          x-conditional: true
        authorization_encrypted_response_enc:
          description: The JWE _enc_ algorithm required for encrypting authorization responses. If _authorization_encrypted_response_alg_ is specified, the default for this value is `A128CBC-HS256`.
          enum:
          - A256GCM
          - A128CBC-HS256
          example: A128CBC-HS256
          type: string
        request_object_signing_alg:
          description: Algorithm which the ADR expects to sign the request object if a request object will be part of the authorization request sent to the Data Holder.
          enum:
          - PS256
          - ES256
          type: string
        software_statement:
          description: The Software Statement Assertion, as defined in the CDR Data Standards.
          format: JWT
          type: string
        software_id:
          description: String representing a unique identifier assigned by the Register and used by registration endpoints to identify the software product to be dynamically registered. <br><br>The _software_id_ will remain the same for the lifetime of the product, across multiple updates and versions.
          example: 740C368F-ECF9-4D29-A2EA-0514A66B0CDE
          type: string
        software_roles:
          default: data-recipient-software-product
          description: String containing a role of the software in the CDR Regime. Initially the only value used will be `data-recipient-software-product`.
          enum:
          - data-recipient-software-product
          example: data-recipient-software-product
          type: string
        scope:
          description: String containing a space-separated list of scope values that the client can use when requesting access tokens.
          example: openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration
          type: string
      required:
      - client_description
      - client_id
      - client_name
      - client_uri
      - grant_types
      - id_token_signed_response_alg
      - jwks_uri
      - logo_uri
      - org_id
      - org_name
      - redirect_uris
      - request_object_signing_alg
      - response_types
      - scope
      - software_id
      - software_statement
      - token_endpoint_auth_method
      - token_endpoint_auth_signing_alg
      type: object
      x-conditional:
      - id_token_encrypted_response_alg
      - id_token_encrypted_response_enc
      - authorization_signed_response_alg
      - authorization_encrypted_response_alg
  requestBodies:
    RequestClientRegistration:
      content:
        application/jwt:
          schema:
            $ref: '#/components/schemas/ClientRegistrationRequestV1'
      description: The registration request JWT to be used to register with a Data Holder.
      required: true