X-Road (NIIS) Initialization API

openapi: 3.2.0
info:
  title: X Road Global Initialization API
  contact:
    email: info@niis.org
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: '1.0'
  description: 'Operations tagged initialization across 4 of this provider''s published API definitions: central-server-admin-openapi.yaml, security-server-admin-openapi.yaml, x-road-global-central-server-admin-openapi.yml, x-road-global-security-server-admin-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: basepath for API v1
  url: /api/v1
security:
- ApiKeyAuth: []
tags:
- name: initialization
  description: resources related to Central Server initialization
paths:
  /initialization:
    post:
      description: 'Administrator initializes a new Central Server with the provided initial configuration.


        This endpoint can also return metadata in the error response. The metadata array can contain error messages about why the init did not succeed. If the pin code is too weak, the error code weak_pin is used and the entries in the metadata array are always ordered in following way


        metadata has a list of strings ["pin_min_length", x, "pin_min_char_classes_count", y] where


        x = the minimum length of the pin code


        y = the minimum amount of character classes (e.g. uppercase, number, special characters) to be used in the pin code


        Other possible error code are


        invalid_init_params for "business" logic problems which can have any one or more of the following strings in the metadata field. There "_exists" -entries are returned if parameter has been given already in partially succeeded initialization. The "_not_provided"-entries are returned if these parameters is needed still for the initialization, but it is not given in the request.


        pin_code_exists


        pin_code_not_provided


        server_address_exists


        server_address_not_provided


        instance_identifier_exists


        instance_identifier_not_provided


        validation_failure for parameter format errors

        See the ''400'' response examples'
      operationId: initCentralServer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitialServerConf'
        description: initial central server configuration
      responses:
        '201':
          description: central server initialized
        '400':
          content:
            application/json:
              examples:
                error_invalid_init_params:
                  $ref: '#/components/examples/ErrorInvalidInitParamsMetadataExample'
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_weak_pin:
                  $ref: '#/components/examples/ErrorWeakPinMetadataExample'
                validation_errors_response:
                  $ref: '#/components/examples/ValidationErrorsExample'
                warnings_response:
                  $ref: '#/components/examples/InitializationWarningExample'
              schema:
                $ref: '#/components/schemas/ErrorInfo'
          description: request was invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Initialize a new central server with the provided initial configuration
      tags:
      - initialization
    servers:
    - description: basepath for API v1
      url: /api/v1
  /initialization/status:
    get:
      description: Administrator checks the initialization status of the Central Server.
      operationId: getInitializationStatus
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitializationStatus'
          description: initialization status of the Central Server
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Check the initialization status of the Central Server
      tags:
      - initialization
    servers:
    - description: basepath for API v1
      url: /api/v1
  /initialization/admin-user:
    post:
      tags:
      - initialization
      summary: Create the initial admin user during Security Server initialization
      operationId: createInitialAdminUser
      description: Creates the initial admin user when database-based authentication is enabled and the Security Server has not yet been initialized. This endpoint is unauthenticated and only usable while no admin user exists. Roles are assigned server-side to mirror the default PAM admin set.
      requestBody:
        description: initial admin user credentials
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitialAdminUser'
      responses:
        '201':
          description: initial admin user created
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo_2'
        '409':
          description: initial admin user creation is not allowed in current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo_2'
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /initialization/admin-user/status:
    get:
      tags:
      - initialization
      summary: Check whether the initial admin user needs to be created
      operationId: getInitialAdminUserStatus
      description: Returns whether the unauthenticated initial admin user creation flow should be offered. True only when database-based authentication is enabled, no admin user exists, and the Security Server has not yet been fully initialized.
      responses:
        '200':
          description: initial admin user creation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitialAdminUserStatus'
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
components:
  responses:
    NotFound:
      description: resource requested does not exists
    InternalServerError:
      description: internal server error
    Forbidden:
      description: request has been refused
    Unauthorized:
      description: authentication credentials are missing
    BadRequest:
      description: request was invalid
  schemas:
    CentralServerAddress:
      description: address of the central server
      properties:
        central_server_address:
          description: Central server’s public DNS name or external IP address
          format: text
          type: string
      required:
      - central_server_address
      type: object
    ErrorInfo:
      $ref: ../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    InstanceIdentifier:
      description: the instance identifier of the Central Server
      properties:
        instance_identifier:
          description: Valid instance identifier, shall not contain colon, semicolon, forwardslash, backslash, percent or control characters.
          example: FI-TEST
          format: text
          maxLength: 255
          minLength: 1
          type: string
          pattern: ^[a-zA-Z0-9'()+,-.=?]*
      required:
      - instance_identifier
      type: object
    TokenInitStatus:
      description: whether a token has been initialized or not – if the token init status cannot be resolved (e.g. signer module is offline), the value is UNKNOWN
      enum:
      - INITIALIZED
      - NOT_INITIALIZED
      - UNKNOWN
      example: INITIALIZED
      type: string
    InitializationStatus:
      allOf:
      - $ref: '#/components/schemas/InstanceIdentifier'
      - $ref: '#/components/schemas/CentralServerAddress'
      description: Initialization status of the Central Server
      properties:
        software_token_init_status:
          $ref: '#/components/schemas/TokenInitStatus'
      required:
      - software_token_init_status
      type: object
    InitialServerConf:
      allOf:
      - $ref: '#/components/schemas/InstanceIdentifier'
      - $ref: '#/components/schemas/CentralServerAddress'
      description: central server initial configuration
      properties:
        software_token_pin:
          description: pin code for the initial software token
          example: sup3rs3cr3t_p!n
          format: text
          maxLength: 255
          minLength: 1
          type: string
      required:
      - software_token_pin
      type: object
    InitialAdminUser:
      type: object
      description: Credentials for the initial admin user created during Security Server initialization
      required:
      - username
      - password
      properties:
        username:
          type: string
          description: Admin user name
          minLength: 3
          maxLength: 30
        password:
          type: string
          description: Admin user password
          minLength: 6
          maxLength: 255
    InitialAdminUserStatus:
      type: object
      description: Whether the initial admin user creation flow should be offered
      required:
      - admin_user_creation_required
      properties:
        admin_user_creation_required:
          type: boolean
          description: true when database-based authentication is enabled, no admin user exists yet, and the Security Server has not been fully initialized
    TokenInitStatus_2:
      type: string
      description: whether a token has been initialized or not – if the software token init status cannot be resolved (e.g. signer module is offline), the value is UNKNOWN
      example: INITIALIZED
      enum:
      - INITIALIZED
      - NOT_INITIALIZED
      - UNKNOWN
    ErrorInfo_2:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    InitializationStatus_2:
      type: object
      description: Initialization status of the Security Server
      required:
      - is_anchor_imported
      - is_server_code_initialized
      - is_server_owner_initialized
      - software_token_init_status
      - enforce_token_pin_policy
      properties:
        is_anchor_imported:
          type: boolean
          description: whether a configuration anchor has been imported or not
        is_server_code_initialized:
          type: boolean
          description: whether the server code of the security server has been initialized or not
        is_server_owner_initialized:
          type: boolean
          description: whether the server owner of the security server has been initialized or not
        software_token_init_status:
          $ref: '#/components/schemas/TokenInitStatus_2'
        enforce_token_pin_policy:
          type: boolean
          description: whether the token pin policy is enforced or not
        software_token_autologin_enabled:
          type: boolean
          description: whether software token autologin is currently enabled
    InitialServerConf_2:
      type: object
      description: security server initial configuration
      properties:
        owner_member_class:
          type: string
          format: text
          description: member class
          example: GOV
          minLength: 1
          maxLength: 255
        owner_member_code:
          type: string
          format: text
          description: member code
          example: 12345678-9
          minLength: 1
          maxLength: 255
        security_server_code:
          type: string
          format: text
          description: security server code
          example: SS1
          minLength: 1
          maxLength: 255
        software_token_pin:
          type: string
          format: text
          description: pin code for the initial software token
          example: sup3rs3cr3t_p!n
          minLength: 1
          maxLength: 255
        ignore_warnings:
          type: boolean
          default: false
          description: if true, any ignorable warnings are ignored. if false (or missing), any warnings cause request to fail
        enable_software_token_autologin:
          type: boolean
          description: if true, enables software token autologin; if false, disables it. If omitted, the autologin setting is left unchanged.
    TokenInitStatus_3:
      type: string
      description: whether a token has been initialized or not – if the software token init status cannot be resolved (e.g. signer module is offline), the value is UNKNOWN
      example: INITIALIZED
      enum:
      - INITIALIZED
      - NOT_INITIALIZED
      - UNKNOWN
    ErrorInfo_3:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    InitializationStatus_3:
      type: object
      description: Initialization status of the Security Server
      required:
      - is_anchor_imported
      - is_server_code_initialized
      - is_server_owner_initialized
      - software_token_init_status
      - enforce_token_pin_policy
      properties:
        is_anchor_imported:
          type: boolean
          description: whether a configuration anchor has been imported or not
        is_server_code_initialized:
          type: boolean
          description: whether the server code of the security server has been initialized or not
        is_server_owner_initialized:
          type: boolean
          description: whether the server owner of the security server has been initialized or not
        software_token_init_status:
          $ref: '#/components/schemas/TokenInitStatus_3'
        enforce_token_pin_policy:
          type: boolean
          description: whether the token pin policy is enforced or not
        software_token_autologin_enabled:
          type: boolean
          description: whether software token autologin is currently enabled
    InitialServerConf_3:
      type: object
      description: security server initial configuration
      properties:
        owner_member_class:
          type: string
          format: text
          description: member class
          example: GOV
          minLength: 1
          maxLength: 255
        owner_member_code:
          type: string
          format: text
          description: member code
          example: 12345678-9
          minLength: 1
          maxLength: 255
        security_server_code:
          type: string
          format: text
          description: security server code
          example: SS1
          minLength: 1
          maxLength: 255
        software_token_pin:
          type: string
          format: text
          description: pin code for the initial software token
          example: sup3rs3cr3t_p!n
          minLength: 1
          maxLength: 255
        ignore_warnings:
          type: boolean
          default: false
          description: if true, any ignorable warnings are ignored. if false (or missing), any warnings cause request to fail
        enable_software_token_autologin:
          type: boolean
          description: if true, enables software token autologin; if false, disables it. If omitted, the autologin setting is left unchanged.
  examples:
    ErrorInvalidInitParamsMetadataExample:
      summary: Initialization error with metadata
      value:
        error:
          code: invalid_init_params
          metadata:
          - server_address_not_provided
          - instance_id_not_provided
          - pin_code_exists
        status: 400
    InitializationWarningExample:
      summary: All initialization warnings example.
      value:
        error:
          code: warnings_detected
        status: 400
        warnings:
        - code: init_software_token_initialized
    ErrorExample:
      $ref: ../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
    ValidationErrorsExample:
      summary: Validation errors response body example
      value:
        error:
          code: validation_failure
          validation_errors:
            initialServerConfDto.instanceIdentifier:
            - IdentifierChars
        status: 400
    ErrorWeakPinMetadataExample:
      summary: Initialization or pin change error with metadata when the provided pin is too weak
      value:
        error:
          code: weak_pin
          metadata:
          - pin_min_length
          - '8'
          - pin_min_char_classes_count
          - '3'
        status: 400
    ErrorInvalidInitParamsMetadataExample_2:
      summary: Initialization error with metadata
      value:
        status: 400
        error:
          code: invalid_init_params
          metadata:
          - server_code_not_provided
          - member_class_not_provided
          - member_code_not_provided
          - pin_code_not_provided
    ErrorExample_2:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
    InitializationWarningExample_2:
      summary: All initialization warnings example.
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
        - code: init_server_id_exists
          metadata:
          - CS/ORG/123/SS1
        - code: init_unregistered_member
          metadata:
          - CS/ORG/123
        - code: init_servercode_exists
        - code: init_server_owner_exists
        - code: init_software_token_initialized
    ValidationErrorsExample_2:
      summary: Validation errors response body example
      value:
        status: 400
        error:
          code: validation_failure
          validation_errors:
            clientAdd.client.memberCode:
            - NoPercent
            clientAdd.client.subsystemCode:
            - NoPercent
            - NoBackslashes
    ErrorInvalidInitParamsMetadataExample_3:
      summary: Initialization error with metadata
      value:
        status: 400
        error:
          code: invalid_init_params
          metadata:
          - server_code_not_provided
          - member_class_not_provided
          - member_code_not_provided
          - pin_code_not_provided
    ErrorExample_3:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
    InitializationWarningExample_3:
      summary: All initialization warnings example.
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
        - code: init_server_id_exists
          metadata:
          - CS/ORG/123/SS1
        - code: init_unregistered_member
          metadata:
          - CS/ORG/123
        - code: init_servercode_exists
        - code: init_server_owner_exists
        - code: init_software_token_initialized
    ValidationErrorsExample_3:
      summary: Validation errors response body example
      value:
        status: 400
        error:
          code: validation_failure
          validation_errors:
            clientAdd.client.memberCode:
            - NoPercent
            clientAdd.client.subsystemCode:
            - NoPercent
            - NoBackslashes
  securitySchemes:
    ApiKeyAuth:
      description: X-Road-ApiKey token=<api key>
      in: header
      name: Authorization
      type: apiKey
x-refined-from:
- central-server-admin-openapi.yaml
- security-server-admin-openapi.yaml
- x-road-global-central-server-admin-openapi.yml
- x-road-global-security-server-admin-openapi.yml