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: '1.5.0'
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/405Error'
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. The requested method is unsupported
definitions:
  RegistrationProperties:
    type: object
    required:
      - client_id
      - client_name
      - client_description
      - client_uri
      - org_id
      - org_name
      - redirect_uris
      - logo_uri
      - jwks_uri
      - software_id
      - scope
      - token_endpoint_auth_signing_alg
      - token_endpoint_auth_method
      - id_token_encrypted_response_alg
      - id_token_encrypted_response_enc
      - request_object_signing_alg
      - 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'
      legal_entity_id:
        description: A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Legal Entity
        type: string
        example: 344F0E809-BDBE-4F8E-BD30-5E6C3CB78D7B
      legal_entity_name:
        description: Human-readable string name of the Accredited Data Recipient Legal Entity
        type: string
        example: Mock Company Pty Ltd.
      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
        type: string
        example: Mock Company Brand.
      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'
        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'
      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](https://consumerdatastandardsaustralia.github.io/standards/#end-points)
        type: string
        example: 'https://www.mockcompany.com.au'
      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
          - ES256
      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 with which an id_token is to be signed
        type: string
        enum:
          - PS256
          - ES256
      id_token_encrypted_response_alg:
        description: JWE `alg` algorithm with which an id_token is to be encrypted
        type: string
        example: RSA-OAEP
      id_token_encrypted_response_enc:
        description: JWE `enc` algorithm with which an id_token is to be encrypted
        type: string
        example: A256GCM
      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
          - ES256
      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
      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`
        type: string
        example: 'data-recipient-software-product'
      scope:
        description: String containing a space-separated list of scope values that the client can use when requesting access tokens.
        type: string
        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'
  ClientRegistration:
    allOf:
      - type: object
        required:
          - iss
          - iat
          - exp
          - jti
          - aud
        properties:
          iss:
            description: Contains the identifier for the ADR Software Product (SoftwareProductId) as defined in the CDR Register
            type: string
            example: CDR Software Product ID
          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'
            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: |
              'Contains the DH issuer value as described in the [OIDC Discovery Document](https://consumerdatastandardsaustralia.github.io/standards/#end-points)''
            type: string
            example: 'https://secure.api.dataholder.com/issuer'
      - $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