openapi: 3.0.0
info:
  version: 0.0.6
  title: Domain Registration API
  description: |
    In order to receive notifications, an API Client must complete event notification subscription. This is a two-step process.
    
    1) The API client must register and receive a domain name from Swift in MVSIPN environment. The client must trigger domain registration from the webserver host to which Swift will eventually route notifications i.e., the API must be triggered from the host that is connected to the VPN Box.
    
    2) The API client must subscribe to specific service and events by doing Notification Subscription APIs. The events published by Service Provider are only delivered when the recipient has an event subscription following the pub/sub model. The API client must indicate the BIC8s and event types on which they want receive events through the API. A webhook endpoint must be defined for each subscription for receiving notifications.
    
    This API Specification covers first step. The API supports registration and returns a routable domain on SWIFT network. The events generated by service provider are delivered to the registered routable domain.
  
  contact:
    name: Developer Hub
    url: https://developer.swift.com
    email: developer-support@swift.com
  license:
    name: API Restricted License
    url: https://developer.swift.com/api-license
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/SWIFT-API/Domain-Registration/0.0.6
  - description: URL for Pilot.
    url: https://api-test.swiftnet.sipn.swift.com/swift-domain-registration/v1
  - description: URL for Live.
    url: https://api.swiftnet.sipn.swift.com/swift-domain-registration/v1
  - description: URL for Sandbox Environment.
    url: https://sandbox.swift.com/swift-domain-registration/v1

security:
  - oauthBearerToken: []
    
tags:
  - name: Domain Registration
    
paths:
  /domains:
    post:
      tags:
        - Domain Registration
      summary: Request creation of a domain.
      description: Register a Domain URL on which an API Client can receive an API call or notification from Service Provider. 
      operationId: createDomainRegistration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Registration'
      responses:
        '201':
          description: Created.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '406':
          $ref: '#/components/responses/406-NotAcceptable'
        '413':
          $ref: '#/components/responses/413-PayloadTooLarge'
        '415':
          $ref: '#/components/responses/415-UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
  /domains/{domain-name}:
    get:
      tags:
        - Domain Registration
      summary: Retrieve a Domain.
      description: Retrieve an existing Domain identified by a domain name.
      operationId: getDomainRegistrations
      parameters:
        # path
        - $ref: '#/components/parameters/domain-name'
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-NotFound'
        '406':
          $ref: '#/components/responses/406-NotAcceptable'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
    
    
    delete:
      tags:
        - Domain Registration
      summary: Delete a domain.
      description: Delete an existing domain identified by domain name.
      operationId: deleteDomainRegistrationsByDomainName
      parameters:
        # path
        - $ref: '#/components/parameters/domain-name'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-NotFound'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
  
  /domains/{domain-name}/metadata:
    put:
      tags:
        - Domain Registration
      summary: Modify an existing domain identified by a domain name.
      description: Modify an existing domain.
      operationId: modifyDomainRegistrationsByDomainName
      parameters:
        # path
        - $ref: '#/components/parameters/domain-name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
                additionalProperties: false
                properties:
                  tls_certificate_thumbprint:
                    description: SHA-256 Thumbprint or Fingerprint of the tls certificate. A certificate thumbprint, also called a fingerprint, is a hash of a certificate, computed over all certificate data and its signature.
                    type: string
                    pattern: ^[0-9a-fA-F]{64}$
                    example : 414c5fedd82a9ad0af50c94e94c91522dfc2cf0c069fd660a6b0403cae3d6500
                  expiry_date_time:
                    description: The subscription expiry date and time in ISODateTime whereby all timezoned dateTime values are UTC.
                    type: string
                    pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.[0-9]+)?(?:Z|[+-][01]\d:[0-5]\d)?$
                    example: 2025-10-16T19:26:15.322Z
                required:
                - tls_certificate_thumbprint
                - expiry_date_time
                
      responses:
        '204':
          description: No Content
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-NotFound'
        '413':
          $ref: '#/components/responses/413-PayloadTooLarge'
        '415':
          $ref: '#/components/responses/415-UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
  
  
components:
  schemas:
    Registration:
      type: object
      description: Register a HTTP domain for receiving notifications on a business service.
      additionalProperties: false
      properties:
        tls_certificate_thumbprint:
          description: SHA-256 Thumbprint or Fingerprint of the tls certificate. A certificate thumbprint, also called a fingerprint, is a hash of a certificate, computed over all certificate data and its signature.
          type: string
          pattern: ^[0-9a-fA-F]{64}$
          example : 414c5fedd82a9ad0af50c94e94c91522dfc2cf0c069fd660a6b0403cae3d6500
        expiry_date_time:
          description: The subscription expiry date and time in ISODateTime whereby all timezoned dateTime values are UTC.
          type: string
          pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.[0-9]+)?(?:Z|[+-][01]\d:[0-5]\d)?$
          example: 2025-10-16T19:26:15.322Z
      required:
      - tls_certificate_thumbprint
      - expiry_date_time
      
    Domain:
      type: object
      description: Domain.
      additionalProperties: false
      properties:
        tls_certificate_thumbprint:
          description: SHA-256 Thumbprint or Fingerprint of the tls certificate. A certificate thumbprint, also called a fingerprint, is a hash of a certificate, computed over all certificate data and its signature.
          type: string
          maxLength: 64
          pattern: ^[0-9a-fA-F]{64}$
          example : 414c5fedd82a9ad0af50c94e94c91522dfc2cf0c069fd660a6b0403cae3d6500
        domain_name:
          description: Routable Domain to which the registered service will publish the POST notification request when the event occurs. Registered Service can also do a GET from API Client on a registered domain name.
          type: string
          format: uri
          example : 51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com
        expiry_date_time:
          description: The subscription expiry date and time in ISODateTime whereby all timezoned dateTime values are UTC.
          type: string
          pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.[0-9]+)?(?:Z|[+-][01]\d:[0-5]\d)?$
          example: 2025-10-16T19:26:15.322Z
        creation_date_time:
          description: Domain Registration creation date and time.
          type: string
          pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.[0-9]+)?(?:Z|[+-][01]\d:[0-5]\d)?$
          example: 2024-08-14T19:26:15.322Z

    
    ErrorMessage:
      description: "Custom error schema to support detailed error message."
      required:
      - code
      - severity
      - text
      type: object
      properties:
        severity:
          description: "Specifies the severity of the error."
          type: string
          enum:
          - Fatal
          - Transient
          - Logic
        code:
          description: "Specifies the custom error code as defined by the service provider."
          type: string
          minLength: 3
          maxLength: 70
        text:
          description: "Specifies the detailed error message identifying the cause of the error."
          type: string
          minLength: 1
          maxLength: 255
       

##############################

  headers:
    X-Request-ID:
      description: "Specify an unique end to end tracking request ID. The element will be populated by the SWIFT API gateway"
      schema:
        type: string
    
  parameters:
    domain-name:
      name: domain-name
      in: path
      description: Routable domain name.
      example : 51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 1024
    site-name:
      name: site-name
      in: path
      description: Site name.
      example : NL-Site
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 100
  responses:
    400-BadRequest:
      description: 'Bad Request'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    401-Unauthorized:
      description: 'Unauthorized'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    403-Forbidden:
      description: 'Forbidden'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    404-NotFound:
      description: 'Not Found'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    405-MethodNotAllowed:
      description: 'Method Not Allowed'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    406-NotAcceptable:
      description: 'Not Acceptable'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    407-ProxyAuthenticationRequired:
      description: 'Proxy Authentication Required'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    409-Conflict:
      description: 'Conflict'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    410-Gone:
      description: 'Gone'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    412-PreconditionFailed:
      description: 'Precondition Failed'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    413-PayloadTooLarge:
      description: 'Payload Too Large'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    415-UnsupportedMediaType:
      description: 'Unsupported Media Type'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    429-TooManyRequests:
      description: 'Too Many Requests'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    500-InternalServerError:
      description: 'Internal Server Error'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    502-BadGateway:
      description: 'Bad Gateway'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    503-ServiceUnavailable:
      description: 'Service Unavailable'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    504-GatewayTimeout:
      description: 'Gateway Timeout'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'

###########################
#  Security Definition    #
###########################            
  securitySchemes:
    oauthBearerToken:
      type: http
      scheme: bearer
      bearerFormat: opaque OAuth 2.0
      description: |
        The access token obtained as a result of OAuth 2.0 flows. SWIFT supports two OAuth grant types for consumption depending on the environment where the API is exposed. 
        
        * MV-SIPN - jwt-bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523) with Signed JWT assertion
        * Internet - Password grant type with license credentials.

        This API uses JWT-Bearer grant type.

        Please visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) page for more information and examples on how to generate an OAuth token.

        In this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.
            
###########################
#       Examples          #
###########################
  # examples: