{
  "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"
    }
  }
}