---
swagger: "2.0"
info:
  description: This specification defines the APIs for Data Holders exposing Dynamic Client Registration endpoints.
  version: 1.13.0
  title: CDR Dynamic Client Registration API
host: data.holder.com.au
basePath: /register
schemes:
- https
consumes:
- application/jwt
produces:
- application/json
paths:
  /register:
    post:
      tags:
      - Client Registration
      summary: Register Data Recipient oAuth Client
      description: Register a client using a CDR Register issued Software Statement Assertion.
      operationId: PostDataRecipientRegistration
      parameters:
      - in: body
        name: ClientRegistrationRequest
        description: The registration request JWT to be used to register with a Data Holder.
        required: true
        schema:
          $ref: '#/definitions/ClientRegistrationRequest'
      responses:
        "201":
          description: Client registration success
          schema:
            $ref: '#/definitions/RegistrationProperties'
        "400":
          description: Request failed due to client error
          schema:
            $ref: '#/definitions/RegistrationError'
  /register/{ClientId}:
    get:
      tags:
      - Client Registration
      summary: Get oAuth Client Registration
      description: Get a Client Registration for a given Client ID.
      operationId: GetClientRegistration
      parameters:
      - name: ClientId
        in: path
        description: The client ID issued by the target Data Holder
        required: true
        type: string
      - name: Authorization
        in: header
        description: "An Authorisation Token as per [RFC6750](https://tools.ietf.org/html/rfc6750)"
        required: true
        type: string
      responses:
        "200":
          description: Client registration retrieval success
          schema:
            $ref: '#/definitions/RegistrationProperties'
        "401":
          description: Request failed due to unknown or invalid Client or invalid access token
          headers:
            WWW-Authenticate:
              type: string
              description: "The Response Header Field as per [RFC6750](https://tools.ietf.org/html/rfc6750)"
              pattern: ^Bearer .*
        "403":
          description: "The client does not have permission to read, update or delete the Client"
      x-scopes:
      - cdr:registration
    put:
      tags:
      - Client Registration
      summary: Update Data Recipient Registration
      description: Update a Client Registration for a given Client ID.
      operationId: PutDataRecipientRegistration
      parameters:
      - in: body
        name: ClientRegistrationRequest
        description: The registration request JWT to be used to register with a Data Holder.
        required: true
        schema:
          $ref: '#/definitions/ClientRegistrationRequest'
      - name: ClientId
        in: path
        description: The client ID issued by the target Data Holder
        required: true
        type: string
      - name: Authorization
        in: header
        description: "An Authorisation Token as per [RFC6750](https://tools.ietf.org/html/rfc6750)"
        required: true
        type: string
      responses:
        "200":
          description: Client registration update success
          schema:
            $ref: '#/definitions/RegistrationProperties'
        "400":
          description: Request failed due to client error
          schema:
            $ref: '#/definitions/RegistrationError'
        "401":
          description: Request failed due to unknown or invalid Client or invalid access token
          headers:
            WWW-Authenticate:
              type: string
              description: "The Response Header Field as per [RFC6750](https://tools.ietf.org/html/rfc6750)"
              pattern: ^Bearer .*
        "403":
          description: "The client does not have permission to read, update or delete the Client"
      x-scopes:
      - cdr:registration
    delete:
      tags:
      - Client Registration
      summary: Delete Data Recipient oAuth Client Registration
      description: Delete a Client Registration for a given Client ID.
      operationId: DeleteDataRecipientRegistration
      parameters:
      - name: ClientId
        in: path
        description: The client ID issued by the target Data Holder
        required: true
        type: string
      - name: Authorization
        in: header
        description: "An Authorisation Token as per [RFC6750](https://tools.ietf.org/html/rfc6750)"
        required: true
        type: string
      responses:
        "204":
          description: Client deleted
        "401":
          description: Request failed due to unknown or invalid Client or invalid access token
          headers:
            WWW-Authenticate:
              type: string
              description: "The Response Header Field as per [RFC6750](https://tools.ietf.org/html/rfc6750)"
              pattern: ^Bearer .*
        "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
      x-scopes:
      - cdr:registration
definitions:
  ClientRegistrationRequest:
    type: string
    format: JWT
    description: The registration request JWT to be used to register with a Data Holder.
    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  RegistrationProperties:
    type: object
    required:
    - client_description
    - client_id
    - client_name
    - client_uri
    - grant_types
    - id_token_encrypted_response_alg
    - id_token_encrypted_response_enc
    - 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
    properties:
      client_id:
        type: string
        example: 35a5a70b-5b8d-41f4-9cbd-96cfbc15c58a
        description: Data Holder issued client identifier string
      client_id_issued_at:
        type: integer
        format: int32
        example: 1571808167
        description: Time at which the client identifier was issued expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC
      client_name:
        type: string
        example: Mock Software
        description: Human-readable string name of the software product to be presented to the end-user during authorization
      client_description:
        type: string
        example: A mock software product
        description: Human-readable string name of the software product description to be presented to the end user during authorization
      client_uri:
        type: string
        example: https://www.mockcompany.com.au
        description: URL string of a web page providing information about the client
      legal_entity_id:
        type: string
        example: 344F0E809-BDBE-4F8E-BD30-5E6C3CB78D7B
        description: A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Legal Entity
      legal_entity_name:
        type: string
        example: Mock Company Pty Ltd.
        description: Human-readable string name of the Accredited Data Recipient Legal Entity
      org_id:
        type: string
        example: 3B0B0A7B-3E7B-4A2C-9497-E357A71D07C8
        description: A unique identifier string assigned by the CDR Register that identifies the Accredited Data Recipient Brand
      org_name:
        type: string
        example: Mock Company Brand.
        description: Human-readable string name of the Accredited Data Recipient to be presented to the end user during authorization
      redirect_uris:
        type: array
        example:
        - https://www.mockcompany.com.au/redirects/redirect1
        - https://www.mockcompany.com.au/redirects/redirect2
        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"
        items:
          type: string
          format: uri
      sector_identifier_uri:
        type: string
        example: https://www.mockcompany.com.au/sector_identifier.json
        description: "URL string referencing the client sector identifier URI, used as an optional input to the Pairwise Identifier"
      logo_uri:
        type: string
        example: https://www.mockcompany.com.au/logos/logo1.png
        description: "URL string that references a logo for the client. If present, the server SHOULD display this image to the end-user during approval"
      tos_uri:
        type: string
        example: https://www.mockcompany.com.au/tos.html
        description: URL string that points to a human-readable terms of service document for the Software Product
      policy_uri:
        type: string
        example: https://www.mockcompany.com.au/policy.html
        description: URL string that points to a human-readable policy document for the Software Product
      jwks_uri:
        type: string
        example: https://www.mockcompany.com.au/jwks
        description: "URL string referencing the client JSON Web Key (JWK) Set [RFC7517] document, which contains the client public keys"
      revocation_uri:
        type: string
        example: https://www.mockcompany.com.au/revocation
        description: URI string that references the location of the Software Product consent revocation endpoint
      recipient_base_uri:
        type: string
        example: https://www.mockcompany.com.au
        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
      token_endpoint_auth_method:
        type: string
        description: The requested authentication method for the token endpoint
        enum:
        - private_key_jwt
      token_endpoint_auth_signing_alg:
        type: string
        description: The algorithm used for signing the JWT
        enum:
        - PS256
        - ES256
      grant_types:
        type: array
        description: Array of OAuth 2.0 grant type strings that the client can use at the token endpoint
        items:
          type: string
          enum:
          - client_credentials
          - authorization_code
          - refresh_token
      response_types:
        type: array
        description: Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint.
        items:
          type: string
          enum:
          - code id_token
      application_type:
        type: string
        description: Kind of the application. The only supported application type will be `web`
        enum:
        - web
      id_token_signed_response_alg:
        type: string
        description: Algorithm with which an id_token is to be signed
        enum:
        - PS256
        - ES256
      id_token_encrypted_response_alg:
        type: string
        example: RSA-OAEP
        description: JWE `alg` algorithm with which an id_token is to be encrypted
      id_token_encrypted_response_enc:
        type: string
        example: A256GCM
        description: JWE `enc` algorithm with which an id_token is to be encrypted
      request_object_signing_alg:
        type: string
        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
      software_statement:
        type: string
        format: JWT
        description: "The Software Statement Assertion, as defined in CDR standards"
      software_id:
        type: string
        example: 740C368F-ECF9-4D29-A2EA-0514A66B0CDE
        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"
      software_roles:
        type: string
        example: data-recipient-software-product
        description: String containing a role of the software in the CDR Regime. Initially the only value used with be `data-recipient-software-product`
      scope:
        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
        description: String containing a space-separated list of scope values that the client can use when requesting access tokens.
  ClientRegistration:
    allOf:
    - type: object
      required:
      - aud
      - exp
      - iat
      - iss
      - jti
      properties:
        iss:
          type: string
          example: CDR Software Product ID
          description: Contains the identifier for the ADR Software Product (SoftwareProductId) as defined in the CDR Register
        iat:
          type: integer
          format: int32
          example: 1571808167
          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
        exp:
          type: integer
          format: int32
          example: 2147483646
          description: The time at which the request expires expressed as seconds since 1970-01-01T00:00:00Z as measured in UTC
        jti:
          type: string
          example: 37747cd1c10545699f754adf28b73e31
          description: "Unique identifier for the JWT, used to prevent replay of the token"
        aud:
          type: string
          example: https://secure.api.dataholder.com/issuer
          description: '''Contains the Data Holder issuer value as described in the OIDC Discovery Document'
    - $ref: '#/definitions/RegistrationProperties'
  RegistrationError:
    type: object
    required:
    - error
    properties:
      error:
        type: string
        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
      error_description:
        type: string
        description: Additional text description of the error for debugging.
parameters:
  Authorization:
    name: Authorization
    in: header
    description: "An Authorisation Token as per [RFC6750](https://tools.ietf.org/html/rfc6750)"
    required: true
    type: string
  ClientId:
    name: ClientId
    in: path
    description: The client ID issued by the target Data Holder
    required: true
    type: string
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:
        type: string
        description: "The Response Header Field as per [RFC6750](https://tools.ietf.org/html/rfc6750)"
        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