{
  "swagger": "2.0",
  "info": {
    "title": "CDR Dynamic Client Registration API",
    "description": "This specification defines the APIs for Data Holders exposing Dynamic Client Registration endpoints\n",
    "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)''\n",
              "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"
        }
      }
    }
  }
}