openapi: "3.0.1"
info:
  title: Dynamic Client Registration API
  description: 
    This specification defines the APIs for a TSP to submit a Software Statement
    Assertion to HSBC for the purpose of creating OAuth clients that are
    registered with HSBC.
  termsOfService: 'https://www.openbanking.org.uk/terms'
  license:
    name: open-licence
    url: 'https://www.openbanking.org.uk/open-licence'
  version: v3.2.1

paths:
  /register:
    post:
      description: Register a client by way of a Software Statement Assertion
      tags:
        - Client Registration
      requestBody:
        description: fields to required to register a TSP
        content:
          application/jose:
            schema:
              type: object
              required:
                - iss
                - iat
                - exp
                - aud
                - jti
                - redirect_uris
                - token_endpoint_auth_method
                - grant_types
                - scope
                - software_statement
                - application_type
                - id_token_signed_response_alg
                - request_object_signing_alg
              properties:
                iss:
                  description: Unique identifier for the TSP. Implemented as Base62 encoded GUID
                  type: string
                  pattern: '^[0-9a-zA-Z]{1,22}$'
                  minLength: 1
                  maxLength: 22
                iat:
                  description: 
                    The time at which the request was issued by the TSP  expressed as
                    seconds since 1970-01-01T00:00:00Z as measured in UTC. The value should be a date or time in the present or in the future.
                  type: integer
                  format: int32
                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
                aud:
                  description: 
                    The audience for the request. This should be the unique identifier
                    for the ASPSP issued by the issuer of the software statement.
                    Implemented as Base62 encoded GUID
                  type: string
                  pattern: '^[0-9a-zA-Z]{1,18}$'
                  minLength: 1
                  maxLength: 18
                jti:
                  description: Unique identifier for the JWT implemented as UUID v4
                  type: string
                  pattern: 
                    ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
                  minLength: 36
                  maxLength: 36
                redirect_uris:
                  type: array
                  description: 
                   Redirect_uri values used by the TSP. One of these registered redirect_uris values MUST exactly match the redirect_uri parameter value used in each Authorization Request
                  items:
                    type: string
                    format: uri
                    minLength: 1
                    maxLength: 256
                token_endpoint_auth_method:
                  type: string
                  description: Requested authentication method for the token endpoint.
                  enum:
                    - private_key_jwt
                grant_types:
                  type: array
                  description: A list of the OAuth 2.0 Grant Types that the TSP is declaring that it will restrict itself to using.
                  items:
                    type: string
                    enum:
                      - client_credentials
                      - authorization_code
                      - refresh_token
                  minItems: 1
                response_types:
                  type: array
                  description: 
                    'A list of the OAuth 2.0 response_type values that the TSP can use at the authorization end point
                    These response types are defined as follows-
                      *  "code": The authorization code response type defined in OAuth
                         2.0, Section 4.1.
                      *  "token": The implicit response type defined in OAuth 2.0,
                         Section 4.2.
                      If the authorization endpoint is used by the grant type, the value
                      of this parameter MUST be the same as the value of the
                      "response_type" parameter passed to the authorization endpoint
                      defined in the grant type definition'
                  items:
                    type: string
                    enum:
                      - code id_token
                software_id:
                  description: 
                      unique ID assigned by TSP. used by registration endpoints to identify the client software to  be dynamically registered.  Unlike "client_id", which is issued by the authorization server and SHOULD vary between instances, the "software_id" SHOULD remain the same for all instances of the  TSP software.  The "software_id" SHOULD remain the same across multiple updates or versions of the same piece of software.  The value of this field is not intended to be human readable.
                  type: string
                  minLength: 1
                  maxLength: 22
                  pattern: '^[0-9a-zA-Z]{1,22}$'
                scope:
                  description: 
                    String containing a space-separated list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the TSP can use when requesting access tokens.
                  type: string
                  minLength: 1
                  maxLength: 256
                software_statement:
                  type: string
                  format: JWT
                application_type:
                  description: 
                        Kind of the application. The default, if omitted, is web.
                        The defined values are native or web.
                        Web OAuth Client using the OAuth Implicit Grant Type must only register URLs using the HTTPS scheme as redirect_uris; they MUST NOT use localhost as the hostname.
                        Native Clients must only register redirect_uris using custom URI schemes or URLs using the HTTP scheme with localhost as the hostname.
                  type: string
                  enum:
                    - web
                    - mobile
                id_token_signed_response_alg:
                  description: The JWS algorithm that is used to sign the ID Token that is issued to this Client
                  $ref: '#/components/schemas/SupportedAlgorithms'
                request_object_signing_alg:
                  description: The type of JSON Web Key Set (JWKS) algorithm that must be used for signing request objects
                  $ref: '#/components/schemas/SupportedAlgorithms'
                token_endpoint_auth_signing_alg:
                  description: The JWS algorithm that is used to sign the JWT that is used to authenticate the Client.
                  $ref: '#/components/schemas/SupportedAlgorithms'
                tls_client_auth_subject_dn:
                  description: 
                    An [RFC4514] string representation of the expected subject distinguished name of the certificate, which the OAuth client will use in mutual TLS authentication.
                    As mentioned in https://tools.ietf.org/html/draft-ietf-oauth-mtls-13#section-2.1.2 if token_endpoint_auth_method = tls_client_auth, then field is mandatory
                  type: string
                  minLength: 1
                  maxLength: 128
                jwks_uri:
                  type: string
                  description: link to obie keystore expressed in URI format
                  format: uri
                  minLength: 1
                  maxLength: 256
                tls_client_certificate_bound_access_tokens:
                  type: boolean
                  description: Indicates authorization server support for mutual-TLS client certificate-bound access tokens
                  enum:
                    - true
                    - false
      responses:
        '201':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/RegistrationResponse'
        '400':
          $ref: '#/components/schemas/400Error'
servers:
  - url: 'https://secure.sandbox.ob.business.hangseng.com/open-banking/v3.2/oauth2'
    description: Register Sandbox endpoint 
  - url: 'https://api.ob.business.hangseng.com/open-banking/v3.2/oauth2'
    description: Register Production endpoint

components:
  schemas:
    SupportedAlgorithms:
      type: string
      enum:
        - PS256
    RegistrationResponse:
      type: object
      required:
        - client_id
      properties:
        client_id:
          description: OAuth 2.0 client identifier string
          type: string
          minLength: 1
          maxLength: 36
        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
          minimum: 0
        grant_types:
          description: A list of the OAuth 2.0 Grant Types that the TSP is declaring that it will restrict itself to using.
          type: array
          items:
            type: string
            enum:
              - client_credentials
              - authorization_code
              - refresh_token
          minItems: 1
        response_types:
          type: array
          description: 
            'A list of the OAuth 2.0 response_type values that the TSP can use at the authorization end point
            These response types are defined as follows-
              *  "code": The authorization code response type defined in OAuth
                 2.0, Section 4.1.
              *  "token": The implicit response type defined in OAuth 2.0,
                Section 4.2.
              If the authorization endpoint is used by the grant type, the value of this parameter MUST be the same as the value of the "response_type" parameter passed to the authorization endpoint defined in the grant type definition'
          items:
            type: string
            enum:
              - code id_token
        redirect_uris:
          type: array
          description: Array of Redirection URI values used by the Client. One of these registered Redirection URI values MUST exactly match the redirect_uri parameter value used in each Authorization Request
          items:
            type: string
            format: uri
            minLength: 1
            maxLength: 256
        token_endpoint_auth_method:
          type: string
          description: Requested authentication method for the token endpoint.
          enum:
            - private_key_jwt
        scope:
          type: string
          description: 
            String containing a space-separated list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the TSP can use when requesting access tokens.
          minLength: 1
          maxLength: 256
        software_statement:
          type: string
          format: JWT
        application_type:
          description: 
            Kind of the application. The default, if omitted, is web. The defined values are native or web.
            Web OAuth Client using the OAuth Implicit Grant Type must only register URLs using the HTTPS scheme as redirect_uris; they MUST NOT use localhost as the hostname.
            Native Clients must only register redirect_uris using custom URI schemes or URLs using the HTTP scheme with localhost as the hostname.
          type: string
          enum:
            - web
            - mobile
        id_token_signed_response_alg:
          description: The JWS algorithm that is used to sign the ID Token that is issued to this Client
          $ref: '#/components/schemas/SupportedAlgorithms'
        request_object_signing_alg:
          description: The type of JSON Web Key Set (JWKS) algorithm that must be used for signing request objects
          $ref: '#/components/schemas/SupportedAlgorithms'
        token_endpoint_auth_signing_alg:
          description: The JWS algorithm that is used to sign the JWT that is used to authenticate the Client.
          $ref: '#/components/schemas/SupportedAlgorithms'
        tls_client_auth_subject_dn:
          type: string
          minLength: 1
          maxLength: 128
          description: 
            An [RFC4514] string representation of the expected subject distinguished name of the certificate,
            which the OAuth client will use in mutual TLS authentication.

            As mentioned in https://tools.ietf.org/html/draft-ietf-oauth-mtls-13#section-2.1.2 if token_endpoint_auth_method = tls_client_auth, then field is mandatory
        tls_client_certificate_bound_access_tokens:
          type: boolean
          description: Indicates authorization server support for mutual-TLS client certificate-bound access tokens
          enum:
            - true
            - false
    400Error:
      $ref: '#/components/schemas/RegistrationError'
    401Error:
      description: 'Request failed due to unknown or invalid Client or invalid access token'
    403Error:
      description: 'The client does not have permission to read, update or delete the Client'
    RegistrationError:
      type: object
      description: Request failed due to client error
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - invalid_redirect_uri
            - invalid_client_metadata
            - invalid_software_statement
            - unapproved_software_statement
        error_description:
          type: string
          minLength: 1
          maxLength: 500
  securitySchemes:
    TPPOAuth2Security:
      type: oauth2
      description: 
        TSP client credential authorisation flow with the ASPSP. No scopes defined
        as per specification
      flows:
        implicit:
          authorizationUrl: 'https://authserver.example/token'
          scopes: {}

