openapi: 3.0.3
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 API
  version: 1.34.1
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:
  parameters:
    HeaderAuthorization:
      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
    PathClientId:
      description: The client ID issued by the target Data Holder.
      explode: false
      in: path
      name: ClientId
      required: true
      schema:
        type: string
      style: simple
  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
  responses:
    PostClientRegistration201:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegistrationProperties'
      description: Client registration success
    GetClientRegistration200:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegistrationProperties'
      description: Client registration retrieval success
    PutClientRegistration200:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegistrationProperties'
      description: Client registration update success
    DCRGeneric400:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegistrationError'
      description: Request failed due to client error
    DCRGeneric401:
      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
    DCRGeneric403:
      description: The client does not have permission to read, update or delete the
        Client
    DCRGeneric405:
      description: Method Not Allowed. The requested method is unsupported
  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
    RegistrationProperties:
      example:
        legal_entity_id: 3B0B0A7B-3E7B-4A2C-9497-E357A71D07C7
        authorization_signed_response_alg: PS256
        token_endpoint_auth_signing_alg: PS256
        client_uri: https://adr.example.com
        application_type: web
        logo_uri: https://adr.example.com/logos/logo1.png
        client_id: 2cfefa98-7d4a-4bcb-95da-47063b84d410
        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: 1574398833
        org_name: Mock Company Brand
        client_name: Mock Software
        policy_uri: https://adr.example.com/policy.html
        id_token_signed_response_alg: PS256
        grant_types:
        - client_credentials
        - authorization_code
        - refresh_token
        redirect_uris:
        - https://adr.example.com/redirects/redirect1
        - https://adr.example.com/redirects/redirect2
        sector_identifier_uri: https://adr.example.com/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://adr.example.com/jwks
        revocation_uri: https://adr.example.com/revocation
        tos_uri: https://adr.example.com/tos.html
        request_object_signing_alg: PS256
        software_roles: data-recipient-software-product
        legal_entity_name: Mock Company Pty Ltd.
        recipient_base_uri: https://adr.example.com
        response_types:
        - code
        - code
      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 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:
          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
    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
        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://mtls.dh.example.com/issuer
          type: string
          x-cds-type: URIString
      required:
      - aud
      - exp
      - iat
      - iss
      - jti
      type: object