{
  "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.36.0"
  },
  "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" : {
        "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 the CDR Data 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"
      }
    }
  }
}