openapi: 3.0.3
info:
  description: This specification defines the APIs for Data Holders exposing Dynamic
    Client Registration endpoints.
  title: CDR Dynamic Client Registration API
  version: 1.24.0
servers:
- url: https://data.holder.com.au/
paths:
  /register:
    post:
      description: "Register a client using a CDR Register issued Software Statement\
        \ Assertion. \n\nThis endpoint does not require CORS."
      operationId: PostDataRecipientRegistration
      requestBody:
        content:
          application/jwt:
            schema:
              $ref: '#/components/schemas/ClientRegistrationRequest'
        description: The registration request JWT to be used to register with a Data
          Holder.
        required: true
      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:
      - Client Registration
      x-codegen-request-body-name: ClientRegistrationRequest
  /register/{ClientId}:
    delete:
      description: Delete a Client Registration for a given Client ID.
      operationId: DeleteDataRecipientRegistration
      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
          x-cds-type: ExternalRef
        style: simple
      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
                x-cds-type: ExternalRef
              style: simple
        "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:
      - 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
          x-cds-type: ExternalRef
        style: simple
      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
                x-cds-type: ExternalRef
              style: simple
        "403":
          description: The client does not have permission to read, update or delete
            the Client
      summary: Get oAuth Client Registration
      tags:
      - Client Registration
      x-scopes:
      - cdr:registration
    put:
      description: Update a Client Registration for a given Client ID.
      operationId: PutDataRecipientRegistration
      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
          x-cds-type: ExternalRef
        style: simple
      requestBody:
        content:
          application/jwt:
            schema:
              $ref: '#/components/schemas/ClientRegistrationRequest'
        description: The registration request JWT to be used to register with a Data
          Holder.
        required: true
      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
                x-cds-type: ExternalRef
              style: simple
        "403":
          description: The client does not have permission to read, update or delete
            the Client
      summary: Update Data Recipient Registration
      tags:
      - Client Registration
      x-scopes:
      - cdr:registration
      x-codegen-request-body-name: ClientRegistrationRequest
components:
  parameters:
    Authorization:
      description: An Authorisation Token as per **[[RFC6750]](#nref-RFC6750)**
      explode: false
      in: header
      name: Authorization
      required: true
      schema:
        type: string
        x-cds-type: ExternalRef
      style: simple
    ClientId:
      description: The client ID issued by the target Data Holder
      explode: false
      in: path
      name: ClientId
      required: true
      schema:
        type: string
      style: simple
  responses:
    "400Error":
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegistrationError'
      description: Request failed due to client error
    "401Error":
      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
            x-cds-type: ExternalRef
          style: simple
    "403Error":
      description: The client does not have permission to read, update or delete the
        Client
    "405Error":
      description: Method Not Allowed. The requested method is unsupported
  schemas:
    ClientRegistrationRequest:
      description: The registration request JWT to be used to register with a Data
        Holder.
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      format: JWT
      type: string
    RegistrationProperties:
      example:
        legal_entity_id: 344F0E809-BDBE-4F8E-BD30-5E6C3CB78D7B
        authorization_signed_response_alg: PS256
        token_endpoint_auth_signing_alg: PS256
        client_uri: https://www.mockcompany.com.au
        application_type: web
        logo_uri: https://www.mockcompany.com.au/logos/logo1.png
        client_id: 35a5a70b-5b8d-41f4-9cbd-96cfbc15c58a
        client_description: A mock software product
        token_endpoint_auth_method: private_key_jwt
        software_statement: software_statement
        software_id: 740C368F-ECF9-4D29-A2EA-0514A66B0CDE
        scope: 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
        client_id_issued_at: 1571808167
        org_name: Mock Company Brand.
        client_name: Mock Software
        policy_uri: https://www.mockcompany.com.au/policy.html
        id_token_signed_response_alg: PS256
        grant_types:
        - client_credentials
        - client_credentials
        redirect_uris:
        - https://www.mockcompany.com.au/redirects/redirect1
        - https://www.mockcompany.com.au/redirects/redirect2
        sector_identifier_uri: https://www.mockcompany.com.au/sector_identifier.json
        authorization_encrypted_response_alg: RSA-OAEP
        authorization_encrypted_response_enc: A128CBC-HS256
        id_token_encrypted_response_alg: RSA-OAEP
        org_id: 3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8
        id_token_encrypted_response_enc: A256GCM
        jwks_uri: https://www.mockcompany.com.au/jwks
        revocation_uri: https://www.mockcompany.com.au/revocation
        tos_uri: https://www.mockcompany.com.au/tos.html
        request_object_signing_alg: PS256
        software_roles: data-recipient-software-product
        legal_entity_name: Mock Company Pty Ltd.
        recipient_base_uri: https://www.mockcompany.com.au
        response_types:
        - code
        - code
      properties:
        client_id:
          description: Data Holder issued client identifier string
          example: 35a5a70b-5b8d-41f4-9cbd-96cfbc15c58a
          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: 1571808167
          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://www.mockcompany.com.au
          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: 344F0E809-BDBE-4F8E-BD30-5E6C3CB78D7B
          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://www.mockcompany.com.au/redirects/redirect1
          - https://www.mockcompany.com.au/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://www.mockcompany.com.au/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://www.mockcompany.com.au/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://www.mockcompany.com.au/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://www.mockcompany.com.au/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://www.mockcompany.com.au/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://www.mockcompany.com.au/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://www.mockcompany.com.au
          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
          x-cds-type: Enum
        token_endpoint_auth_signing_alg:
          description: The algorithm used for signing the JWT
          enum:
          - PS256
          - ES256
          type: string
          x-cds-type: Enum
        grant_types:
          description: Array of OAuth 2.0 grant type strings that the client can use
            at the token endpoint
          items:
            enum:
            - client_credentials
            - authorization_code
            - refresh_token
            type: string
            x-cds-type: Enum
          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. Response type value `code id_token`
            is required for OIDC Hybrid Flow.
          items:
            enum:
            - code
            - code id_token
            type: string
            x-cds-type: Enum
          type: array
        application_type:
          description: Kind of the application. The only supported application type
            will be `web`
          enum:
          - web
          type: string
          x-cds-type: Enum
        id_token_signed_response_alg:
          description: Algorithm with which an id_token is to be signed
          enum:
          - PS256
          - ES256
          type: string
          x-cds-type: Enum
        id_token_encrypted_response_alg:
          description: JWE `alg` algorithm with which an id_token is to be encrypted.<br/><br/>Required
            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
            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
          x-cds-type: Enum
        software_statement:
          description: The Software Statement Assertion, as defined in CDR 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:
          description: String containing a role of the software in the CDR Regime.
            Initially the only value used with be `data-recipient-software-product`
          enum:
          - data-recipient-software-product
          example: data-recipient-software-product
          type: string
          x-cds-type: Enum
        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
    ClientRegistration:
      allOf:
      - $ref: '#/components/schemas/ClientRegistration_allOf'
      - $ref: '#/components/schemas/RegistrationProperties'
    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
          x-cds-type: Enum
        error_description:
          description: Additional text description of the error for debugging.
          type: string
          x-cds-type: ASCIIString
      required:
      - error
      type: object
    ClientRegistration_allOf:
      properties:
        iss:
          description: Contains the identifier for the ADR Software Product (SoftwareProductId)
            as defined in the CDR Register
          example: CDR Software Product ID
          type: string
        iat:
          description: The time at which the request was issued by the Data Recipient  expressed
            as seconds since 1970-01-01T00:00:00Z as measured in UTC
          example: 1571808167
          type: integer
          x-cds-type: ExternalRef
        exp:
          description: The time at which the request expires expressed as seconds
            since 1970-01-01T00:00:00Z as measured in UTC
          example: 2147483646
          type: integer
          x-cds-type: ExternalRef
        jti:
          description: Unique identifier for the JWT, used to prevent replay of the
            token
          example: 37747cd1c10545699f754adf28b73e31
          type: string
        aud:
          description: '''Contains the Data Holder issuer value as described in the
            OIDC Discovery Document'
          example: https://secure.api.dataholder.com/issuer
          type: string
          x-cds-type: URIString
      required:
      - aud
      - exp
      - iat
      - iss
      - jti
      type: object