swagger: '2.0'
info:
  title: CDR Dynamic Client Registration API
  description: >
    This specification defines the APIs for Data Holders exposing Dynamic Client Registration endpoints
  version: '0.1'
schemes:
  - https
consumes:
  - application/jwt
produces:
  - application/json
paths:
  /register:
    post:
      summary: Register a client using a CDR Register issued Software Statement Assertion
      tags:
        - Client Registration
      parameters:
        - $ref: '#/parameters/ClientRegistrationRequest'
      responses:
        '201':
          description: Client registration success
          schema:
            $ref: '#/definitions/RegistrationProperties'
        '400':
          $ref: '#/responses/400Error'
  '/register/{ClientId}':
    get:
      summary: Get a Client Registration for a given Client ID
      tags:
        - Client Registration
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/Authorization'
      responses:
        '200':
          description: Client registration retrieval success
          schema:
            $ref: '#/definitions/RegistrationProperties'
        '401':
          $ref: '#/responses/401Error'
        '403':
          $ref: '#/responses/403Error'
    put:
      summary: Update a Client Registration for a given Client ID
      tags:
        - Client Registration
      parameters:
        - $ref: '#/parameters/ClientRegistrationRequest'
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/Authorization'
      responses:
        '200':
          description: Client registration update success
          schema:
            $ref: '#/definitions/RegistrationProperties'
        '400':
          $ref: '#/responses/400Error'
        '401':
          $ref: '#/responses/401Error'
        '403':
          $ref: '#/responses/403Error'
    delete:
      summary: Delete a Client Registration for a given Client ID
      tags:
        - Client Registration
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/Authorization'
      responses:
        '204':
          description: Client deleted
        '401':
          $ref: '#/responses/401Error'
        '403':
          $ref: '#/responses/403Error'
        '405':
          $ref: '#/responses/403Error'
parameters:
  Authorization:
    in: header
    name: Authorization
    type: string
    required: true
    description: 'An Authorisation Token as per [RFC6750](https://tools.ietf.org/html/rfc6750)'
  ClientId:
    in: path
    name: ClientId
    description: The client ID issued by the target Data Holder
    type: string
    required: true
  ClientRegistrationRequest:
    in: body
    name: ClientRegistrationRequest
    description: 'The registration request JWT, as defined in [Dynamic Client Registration](https://cdr-register.github.io/register/#dynamic-client-registration), to be used to register with a Data Holder'
    required: true
    schema:
      type: string
      format: JWT
      example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
responses:
  400Error:
    description: Request failed due to client error
    schema:
      $ref: '#/definitions/RegistrationError'
  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](https://tools.ietf.org/html/rfc6750)'
        type: string
        pattern: ^Bearer .*
  403Error:
    description: 'The client does not have permission to read, update or delete the Client'
  405Error:
    description: Method Not Allowed
definitions:
  RegistrationProperties:
    type: object
    required:
      - client_id
      - client_name
      - client_description
      - client_uri
      - org_id
      - org_name
      - redirect_uris
      - logo_uri
      - jwks_uri
      - revocation_uri
      - software_id
      - software_roles
      - scope
      - token_endpoint_auth_signing_alg
      - token_endpoint_auth_method
      - grant_types
      - response_types
      - software_statement
    properties:
      client_id:
        description: Data Holder issued client identifier string
        type: string
        example: '35a5a70b-5b8d-41f4-9cbd-96cfbc15c58a'
      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
        type: integer
        format: int32
        example: 1571808167
      client_name:
        description: 'Human-readable string name of the software product to be presented to the end-user during authorization'
        type: string
        example: 'Mock Software'
      client_description:
        description: 'Human-readable string name of the software product description to be presented to the end user during authorization'
        type: string
        example: 'A mock software product'
      client_uri:
        description: 'URL string of a web page providing information about the client'
        type: string
        example: 'https://www.mockcompany.com.au'
      org_id:
        description: 'A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Brand'
        type: string
        example: '3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8'
      org_name:
        description: 'Human-readable string name of the Accredited Data Recipient to be presented to the end user during authorization'
        example: 'Mock Company Inc.'
        type: string
      redirect_uris:
        description: 'Array of redirection URI strings for use in redirect-based flows'
        type: array
        items:
          type: string
          format: uri
        example: ['https://www.mockcompany.com.au/redirects/redirect1', 'https://www.mockcompany.com.au/redirects/redirect2']
      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'
        type: string
        example: 'https://www.mockcompany.com.au/logos/logo1.png'
      tos_uri:
        description: 'URL string that points to a human-readable terms of service document for the Software Product'
        type: string
        example: 'https://www.mockcompany.com.au/tos.html'
      policy_uri:
        description: 'URL string that points to a human-readable policy document for the Software Product'
        type: string
        example: 'https://www.mockcompany.com.au/policy.html'
      jwks_uri:
        description: 'URL string referencing the client JSON Web Key (JWK) Set [RFC7517] document, which contains the client public keys'
        type: string
        example: 'https://www.mockcompany.com.au/jwks'
      revocation_uri:
        description: 'URI string that references the location of the Software Product consent revocation endpoint'
        type: string
        example: 'https://www.mockcompany.com.au/revocation'
      token_endpoint_auth_method:
        description: 'The requested authentication method for the token endpoint'
        type: string
        enum:
          - private_key_jwt
      token_endpoint_auth_signing_alg:
        description: 'The algorithm used for signing the JWT'
        type: string
        enum:
          - PS256
      grant_types:
        description: 'Array of OAuth 2.0 grant type strings that the client can use at the token endpoint'
        type: array
        items:
          type: string
          enum:
            - client_credentials
            - authorization_code
            - refresh_token
      response_types:
        description: 'Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint.'
        type: array
        items:
          type: string
          enum:
            - code id_token
      application_type:
        description: 'Kind of the application. The only supported application type will be `web`'
        type: string
        enum:
          - web
      id_token_signed_response_alg:
        description: 'Algorithm which the ADR expects id_token to be signed with, if an id_token is returned'
        type: string
        enum:
          - PS256
      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'
        type: string
        enum:
          - PS256
      software_statement:
        description: 'The Software Statement Assertion, as defined in [Dynamic Client Registration](https://cdr-register.github.io/register/#dynamic-client-registration)'
        type: string
        format: JWT
      software_id:
        description: 'String representing a unique identifier assigned by the ACCC 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'
        type: string
        example: '740C368F-ECF9-4D29-A2EA-0514A66B0CDE'
      scope:
        description: 'String containing a space-separated list of scope values that the client can use when requesting access tokens.'
        type: string
        example: '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'

  ClientRegistration:
    allOf:
      - type: object
        required:
          - iss
          - iat
          - exp
          - jti
          - aud
        properties:
          iss:
            description: Unique identifier for the Data Holder issued by the CDR Register
            type: string
            example: 'Mock Company'
          iat:
            description: >-
              The time at which the request was issued by the TPP  expressed as
              seconds since 1970-01-01T00:00:00Z as measured in UTC
            type: integer
            format: int32
            example: 1571808167
          exp:
            description: >-
              The time at which the request expires expressed as seconds since
              1970-01-01T00:00:00Z as measured in UTC
            type: integer
            format: int32
            example: 2147483646
          jti:
            description: Unique identifier for the JWT, used to prevent replay of the token
            type: string
            example: '37747cd1c10545699f754adf28b73e31'
          aud:
            description: |
              The audience for the request. This should be the Data Holder authorisation server URI
            type: string
            example: 'https://secure.api.dataholder.com'
      - $ref: '#/definitions/RegistrationProperties'
  RegistrationError:
    type: object
    required:
      - error
    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)'
        type: string
        enum:
          - invalid_redirect_uri
          - invalid_client_metadata
          - invalid_software_statement
          - unapproved_software_statement
      error_description:
        description: 'Additional text description of the error for debugging.'
        type: string