---
openapi: 3.0.0
info:
  description: X-Road Security Server Admin API. Note that the error metadata responses described in some endpoints are subjects to change and may be updated in upcoming versions.
  version: "2.1.0"
  title: X-Road Security Server Admin API
  contact:
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
    email: info@niis.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: /api/v1
    description: basepath for API v1
tags:
  - name: backups
    description: backup endpoints
  - name: certificate-authorities
    description: CA endpoints
  - name: clients
    description: clients endpoints
  - name: diagnostics
    description: diagnostics endpoints
  - name: endpoints
    description: services' endpoints related endpoints
  - name: initialization
    description: initialization endpoints
  - name: keys
    description: keys endpoints
  - name: language
    description: language endpoints
  - name: local-groups
    description: local groups endpoints
  - name: member-classes
    description: member classes endpoints
  - name: member-names
    description: member names endpoints
  - name: security-servers
    description: security servers endpoints
  - name: services
    description: services endpoints
  - name: service-descriptions
    description: service descriptions endpoints
  - name: system
    description: system endpoints
  - name: timestamping
    description: timestamping endpoints
  - name: token-certificate
    description: token certificates endpoints
  - name: tokens
    description: tokens endpoints
  - name: x-road-instances
    description: x-road-instances endpoints
paths:
  /backups:
    get:
      tags:
        - backups
      summary: get security server backups
      operationId: getBackups
      description: <h3>Administrator views the backups for the security server.</h3>
      responses:
        '200':
          description: list of security server backups
          content:
            application/json:
              schema:
                type: array
                description: array of backup objects
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/Backup'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - backups
      summary: add new backup for the security server
      operationId: addBackup
      description:
        <h3>Adds security server backup to the system.</h3>
        <p>This endpoint can also return metadata in the error response. The metadata array contains the output of a failed backup generation script.</p>
      responses:
        '201':
          description: item created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Backup'
        '202':
          description: item accepted
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /backups/ext:
    post:
      tags:
        - backups
      summary: add new backup for the security server and return extra backup state
      operationId: addBackupExt
      description:
        <h3>Adds security server backup to the system.</h3>
        <p>This endpoint can also return metadata in the error response. The metadata array contains the output of a failed backup generation script.</p>
      responses:
        '201':
          description: item created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupExt'
        '202':
          description: item accepted
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /backups/upload:
    post:
      tags:
        - backups
      summary: upload new backup for the security server
      operationId: uploadBackup
      description:
        <h3>Uploads new security server backup to the system.</h3>
        <p>Note that it is possible to overwrite an existing backup file with the same name.
        <ul>
        <li>Attempt to upload a new backup file having the same name with an existing backup and with query parameter <code>ignore_warnings</code> = false causes the operation to fail with a warning in response's ErrorInfo object.</li>
        <li>Attempt to upload a new backup file having the same name with an existing backup and with query parameter <code>ignore_warnings</code> = true will overwrite the existing backup.</li>
        </ul>
        </p>
        <p>The warning response has a warning code <code>warning_file_already_exists</code> and the metadata field contains the name of the existing backup</p>
      parameters:
        - in: query
          name: ignore_warnings
          description: If true, any ignorable warnings are ignored. if false (or missing),
            any warnings cause request to fail.
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        description: backup to add
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BackupArchive'
      responses:
        '201':
          description: item created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Backup'
        '202':
          description: item accepted
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                warnings_response:
                  $ref: '#/components/examples/UploadExistingBackupWarningExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /backups/{filename}:
    delete:
      tags:
        - backups
      summary: delete security server backup
      operationId: deleteBackup
      description: <h3>Administrator deletes the backup of the security server.</h3>
      parameters:
        - in: path
          name: filename
          description: filename of the backup
          required: true
          schema:
            type: string
            format: filename
            minLength: 1
            maxLength: 255
      responses:
        '204':
          description: deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /backups/{filename}/restore:
    put:
      tags:
        - backups
      summary: restore security server configuration from backup
      operationId: restoreBackup
      description:
        <h3>Administrator restores the security server configuration from backup.</h3>
        <p>This endpoint can also return metadata in the error response. The metadata array contains the output of a failed backup restore script.</p>
      parameters:
        - in: path
          name: filename
          description: filename of the backup
          required: true
          schema:
            type: string
            format: filename
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: restore was successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokensLoggedOut'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /backups/{filename}/download:
    get:
      tags:
        - backups
      summary: download security server backup
      operationId: downloadBackup
      description: <h3>Administrator downloads the backup of the security server.</h3>
      parameters:
        - in: path
          name: filename
          description: filename of the backup
          required: true
          schema:
            type: string
            format: filename
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: backup file downloaded
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: backup file
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /token-certificates:
    post:
      tags:
        - token-certificates
      summary: import new certificate
      operationId: importCertificate
      description:
        <h3>Imports certificate to the system.</h3>
        <p>This endpoint can also return metadata in the error response if the client for the certificate is not found. The metadata array contains the identifier of that client.</p>
      requestBody:
        description: certificate to import
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CertificateFile'
      responses:
        '201':
          description: certificate created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCertificate'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /token-certificates/{hash}:
    get:
      tags:
        - token-certificates
      summary: get certificate information
      operationId: getCertificate
      description: <h3>Administrator views certificate details.</h3>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '200':
          description: token certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCertificate'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    delete:
      tags:
        - token-certificates
      summary: delete certificate
      operationId: deleteCertificate
      description:
        <h3>Administrator deletes the certificate.</h3>
        <p>This endpoint can also return metadata in the error response if the certificate is not found. The metadata array contains the id of that certificate.</p>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: deletion was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /token-certificates/{hash}/activate:
    put:
      tags:
        - token-certificates
      summary: activate certificate
      operationId: activateCertificate
      description: <h3>Administrator activates selected certificate.</h3>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: request was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /token-certificates/{hash}/disable:
    put:
      tags:
        - token-certificates
      summary: deactivate certificate
      operationId: disableCertificate
      description: <h3>Administrator deactivates selected certificate.</h3>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: certificate was deactivated
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /token-certificates/{hash}/import:
    post:
      tags:
        - token-certificates
      summary: import an existing certificate from a token by cert hash
      operationId: importCertificateFromToken
      description:
        <h3>Imports certificate from a token to the system.</h3>
        <p>This endpoint can also return metadata in the error response if the client for this certificate is not found. The metadata contains the identifier of that client.</p>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '201':
          description: the imported certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCertificate'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /token-certificates/{hash}/possible-actions:
    get:
      tags:
        - token-certificates
      summary: get possible actions for one certificate
      operationId: getPossibleActionsForCertificate
      description: <h3>UI needs to know which actions can be done on one certificate.</h3>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '200':
          description: possible actions that can be done on the certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PossibleActions'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /token-certificates/{hash}/register:
    put:
      tags:
        - token-certificates
      summary: register certificate
      operationId: registerCertificate
      description: <h3>Administrator registers selected certificate.</h3>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityServerAddress'
      responses:
        '200':
          description: request was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /token-certificates/{hash}/unregister:
    put:
      tags:
        - token-certificates
      summary: unregister authentication certificate
      operationId: unregisterAuthCertificate
      description:
        <h3>Administrator unregisters selected authentication certificate.</h3>
        <p>This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: request was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /token-certificates/{hash}/mark-for-deletion:
    put:
      tags:
        - token-certificates
      summary: marks an auth certificate for deletion
      operationId: markAuthCertForDeletion
      description:
        <h3>Administrator marks an auth certificate for deletion.</h3>
        <p>This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
      parameters:
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: request was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /clients:
    get:
      tags:
        - clients
      summary: find security server clients
      operationId: findClients
      description: <h3>Administrator views the clients of the security server.</h3>
      parameters:
        - in: query
          name: name
          description: pass an optional search string (name) for looking up clients
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: instance
          description: pass an optional search string (instance) for looking up clients
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: member_class
          description: pass an optional search string (member_class) for looking up clients
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: member_code
          description: pass an optional search string (member_code) for looking up clients
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: subsystem_code
          description: pass an optional search string (subsystem_code) for looking up clients
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: show_members
          description: to include members for search results
          required: false
          schema:
            type: boolean
            default: true
        - in: query
          name: internal_search
          description: to search only clients inside security server
          required: false
          schema:
            type: boolean
            default: true
        - in: query
          name: local_valid_sign_cert
          description:
            To search only clients that have (or don't have) a valid (registered, OCSP response GOOD) sign cert stored on this security server.
            Can be used to search both local and global clients, and can be combined with <code>internal_search</code> and <code>exclude_local</code> parameters.
            True = limit to clients that have a valid local sign cert, false = limit to clients that don't have a valid local sign cert.
          required: false
          schema:
            type: boolean
        - in: query
          name: exclude_local
          description: to search only clients that are not added to this security server
          required: false
          schema:
            type: boolean
            default: false
        - in: query
          name: include_management_service_check
          description: add info, is this subsystem management service provider or not
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: list of clients
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of client objects
                items:
                  $ref: '#/components/schemas/Client'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - clients
      summary: Add new client for the security server.
      operationId: addClient
      description:
        <h3>Adds new client to the system.</h3>
        <p>The client id will be validated and if the validation fails a validation error is returned. Note that with this endpoint it is possible to add an unregistered member as a client.
        <ul>
        <li>Attempt to add an unregistered member with <code>ClientAdd.ignore_warnings</code> = false causes the operation to fail with a warning in response's ErrorInfo object.</li>
        <li>Attempt to add an unregistered member with <code>ClientAdd.ignore_warnings</code> = true succeeds.</li>
        </ul>
        </p>
        <p>When trying to add an unregister client, the error response has an error code <code>unregistered_member</code> and the metadata field contains the identifier of the unregistered client</p>
      requestBody:
        description: client to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientAdd'
      responses:
        '201':
          description: new client created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '400':
          description: there are warnings or errors related to the service description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                warnings_response:
                  $ref: '#/components/examples/AddUnregisteredMemberWarningExample'
                validation_errors_response:
                  $ref: '#/components/examples/ValidationErrorsExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /clients/{id}:
    get:
      tags:
        - clients
      summary: get security server client information
      operationId: getClient
      description: <h3>Administrator views the client details of the security server.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: client object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    patch:
      tags:
        - clients
      summary: update security server client information
      operationId: updateClient
      description: <h3>Administrator updates the client information.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionTypeWrapper'
      responses:
        '200':
          description: client modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    delete:
      tags:
        - clients
      summary: delete security server client
      operationId: deleteClient
      description: <h3>Administrator deletes the client of the security server.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '204':
          description: client deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /clients/{id}/local-groups:
    get:
      tags:
        - clients
      summary: get local groups for the selected client
      operationId: getClientLocalGroups
      description: <h3>Administrator views the local groups for the client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: list of local groups
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of local group objects
                items:
                  $ref: '#/components/schemas/LocalGroup'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - clients
      summary: add new local group for the security server client
      operationId: addClientLocalGroup
      description: <h3>Administrator adds a new local group for the client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      requestBody:
        description: group to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocalGroupAdd'
      responses:
        '201':
          description: local group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocalGroup'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /clients/{id}/orphans:
    get:
      tags:
        - clients
      summary: get information about orphaned sign keys, certificates and csrs left behind a delete client
      operationId: getClientOrphans
      description:
        <h3>Administrator has deleted a client and wants to know if some orphaned sign keys, certificates or csrs exist.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: Information telling that orphans exist. If they don't exist, 404 is returned instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrphanInformation'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
    delete:
      tags:
        - clients
      summary: delete orphaned sign keys, certificates and csrs left behind a delete client
      operationId: deleteOrphans
      description: <h3>Administrator deletes the orphaned sign keys, certificates and csrs left behind a delete client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '204':
          description: deletion was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /clients/{id}/register:
    put:
      tags:
        - clients
      summary: register security server client
      operationId: registerClient
      description:
        <h3>Administrator registers client.</h3>
        <p>This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '204':
          description: client was registered
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /clients/{id}/security-servers:
    get:
      tags:
        - clients
      summary: get all clients security servers
      operationId: getClientSecurityServers
      description: <h3>Administrator views the details of clients security servers.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: list of SecurityServer objects
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of SecurityServer objects
                items:
                  $ref: '#/components/schemas/SecurityServer'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /clients/{id}/service-clients:
    get:
      tags:
        - clients
      summary: get service clients for the selected client's services
      operationId: getClientServiceClients
      description: <h3>Administrator views the service clients for the client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: list of service clients
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of service client objects
                items:
                  $ref: '#/components/schemas/ServiceClient'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /clients/{id}/service-clients/{sc_id}:
    get:
      tags:
        - clients
      summary: get single service client by client id and service client id
      operationId: getServiceClient
      description: <h3>Administrator views the information for a single service client.<h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
        - in: path
          name: sc_id
          description: id of the service client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: single service clients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceClient'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /clients/{id}/service-clients/{sc_id}/access-rights:
    get:
      tags:
        - clients
      summary: get access rights for the selected service client.
      operationId: getServiceClientAccessRights
      description: <h3>Administrator views service client's access rights.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client who owns the services
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
        - in: path
          name: sc_id
          description: id of the service client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1279
      responses:
        '200':
          description: list of access rights
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of access right objects
                items:
                  $ref: '#/components/schemas/AccessRight'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - clients
      summary: Add new access rights for selected service client. If service client did not exist yet, one is created.
      operationId: addServiceClientAccessRights
      description: <h3>Adds access rights to the service client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client who owns the services
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
        - in: path
          name: sc_id
          description: id of the service client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1279
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessRights'
      responses:
        '201':
          description: access right that was added
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of added access right objects
                items:
                  $ref: '#/components/schemas/AccessRight'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /clients/{id}/service-clients/{sc_id}/access-rights/delete:
    post:
      tags:
        - clients
      summary: remove access rights
      operationId: deleteServiceClientAccessRights
      description: <h3>Administrator removes access rights from selected service client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client who owns the services
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
        - in: path
          name: sc_id
          description: id of the service client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1279
      requestBody:
        description: list of access rights to be deleted
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessRights'
      responses:
        '204':
          description: access right(s) deleted
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /clients/{id}/sign-certificates:
    get:
      tags:
        - clients
      summary: get security server client certificates information
      operationId: getClientSignCertificates
      description: <h3>Administrator views the certificates for the client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: list of certificates
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of certificate (details) objects
                items:
                  $ref: '#/components/schemas/TokenCertificate'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /clients/{id}/tls-certificates:
    get:
      tags:
        - clients
      summary: get security server client TLS certificates information
      operationId: getClientTlsCertificates
      description: <h3>Administrator views the TLS certificates for the client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: list of tls certificates
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of certificate (details) objects
                items:
                  $ref: '#/components/schemas/CertificateDetails'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - clients
      summary: add new certificate for the security server client
      operationId: addClientTlsCertificate
      description: <h3>Administrator adds a new certificate for the client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      requestBody:
        description: certificate to add
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CertificateFile'
      responses:
        '201':
          description: certificate added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateDetails'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /clients/{id}/tls-certificates/{hash}:
    get:
      tags:
        - clients
      summary: get TLS certificate
      operationId: getClientTlsCertificate
      description: <h3>Administrator gets the TLS certificate for the selected client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
            pattern: ^[a-fA-F0-9]+
      responses:
        '200':
          description: certificate details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateDetails'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    delete:
      tags:
        - clients
      summary: delete certificate
      operationId: deleteClientTlsCertificate
      description: <h3>Administrator deletes the certificate from selected client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
        - in: path
          name: hash
          description: SHA-256 hash of the certificate
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 64
      responses:
        '204':
          description: certificate deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /clients/{id}/unregister:
    put:
      tags:
        - clients
      summary: unregister security server client
      operationId: unregisterClient
      description:
        <h3>Administrator unregisters client.</h3>
        <p>This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '204':
          description: unregister was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /clients/{id}/service-descriptions:
    get:
      tags:
        - clients
      summary: get security server client service descriptions
      operationId: getClientServiceDescriptions
      description: <h3>Administrator views the service descriptions for the client.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: list of service descriptions
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of service description objects
                items:
                  $ref: '#/components/schemas/ServiceDescription'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '500':
          description: internal server error
    post:
      tags:
        - clients
      summary: add new service description for the security server client
      operationId: addClientServiceDescription
      description:
        <h3>Administrator adds a new service description for the client.</h3>
        <p>
        This endpoint can also return metadata in the error response if adding the service description fails due to invalid URLs, already existing service description or already existing services.
        If adding the service description fails due to an invalid service URL, the error response will have the error code <code>invalid_service_url</code> and the metadata will contain a list of invalid URLs.
        If adding the service description fails due to an already existing service description, the error response will have the error code <code>url_already_exists</code> and the metadata will contain the existing URL.
        If adding the service description fails due to already existing services, the metadata array will have a more complex format. See the description of the '409' response in this endpoint.
        </p>
        <p>
        This endpoint can return a warnings response which can be ignored by setting <code>ServiceDescriptionAdd.ignore_warnings</code> = true.
        If <code>ServiceDescriptionAdd.ignore_warnings</code> = false, a warnings response will be returned if WSDL or OpenAPI3 validation fails and validation warnings are returned.
        The warnings will have the warning code <code>wsdl_validation_warnings</code> or <code>openapi_validation_warnings</code> depending on which type the service description is. The metadata of the warning contains the output of the validator itself.
        </p>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceDescriptionAdd'
      responses:
        '201':
          description: service description created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
        '400':
          description: there are warnings or errors related to the service description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                warnings_response:
                  $ref: '#/components/examples/AddServiceDescriptionWarningExample'
                validation_errors_response:
                  $ref: '#/components/examples/ValidationErrorsExample'

        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description:
            <h3>An existing item already exists</h3>
            <p>
            If there are existing WSDL services with the same name, the error response will include the existing services' names and the containing WSDL's URL in the metadata array.
            </p>
            <p>
            In this case the error code <code>service_already_exists</code> (WSDL) or <code>service_code_already_exists</code> (OPENAPI3) is used and the entries in the metadata array are ordered in following way
            <ul>
            <li>metadata has a list of strings [C1,U1,C2,U2....Cn,Un] where</li>
            <li>C1 = duplicate service full code</li>
            <li>U1 = URL of the existing WSDL that has the duplicate</li>
            </ul>
            </p>
            <strong>See the example</strong>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ServiceDescriptionErrorWithMetadataExample'
        '500':
          description: internal server error
  /clients/{id}/service-client-candidates:
    get:
      tags:
        - clients
      summary: find ServiceClient candidates for a specific client
      operationId: findServiceClientCandidates
      description:
        <h3>Administrator views the clients, globalgroups and localgroups, that could be added as ServiceClients for given Client's services.</h3>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
        - in: query
          name: member_name_group_description
          description: pass an optional search string (name) for looking up subjects - name of a member or description of a group
          example: NIIS | Some group description
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: service_client_type
          description: pass an optional search string (service_client_type) for looking up service clients
          required: false
          schema:
            $ref: '#/components/schemas/ServiceClientType'
        - in: query
          name: instance
          description: pass an optional search string (instance) for looking up service clients - full instance id should be used
          example: GOV
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: member_class
          description: pass an optional search string (member_class) for looking up service clients
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: member_group_code
          description: pass an optional search string (member_group_code) for looking up service clients - member_code of a member or group_code of a group
          example: 1234 | Example group code
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
        - in: query
          name: subsystem_code
          description: pass an optional search string (subsystem_code) for looking up service clients
          example: Subsystem1
          required: false
          schema:
            type: string
            format: text
            minLength: 0
            maxLength: 255
      responses:
        '200':
          description: list of service clients
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of ServiceClients
                items:
                  $ref: '#/components/schemas/ServiceClient'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /clients/{id}/make-owner:
    put:
      tags:
        - clients
      summary: make client Security Server's owner. Client must be a member and already registered on the Security Server
      operationId: changeOwner
      description:
        <h3>Administrator changes Security Server's owner.</h3>
        <p>This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
      parameters:
        - in: path
          name: id
          description: id of the client to be set as owner
          required: true
          schema:
            type: string
            example: FI:GOV:123
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '204':
          description: client was set as owner
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /clients/{id}/disable:
    put:
      tags:
        - clients
      summary: disable security server client
      operationId: disableClient
      description:
        <h3>Administrator disables client.</h3>
        <p>This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '204':
          description: disabling was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /clients/{id}/enable:
    put:
      tags:
        - clients
      summary: enable security server client
      operationId: enableClient
      description:
        <h3>Administrator enables client.</h3>
        <p>This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '204':
          description: enabling was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /clients/{id}/rename:
    put:
      tags:
        - clients
      summary: rename security server client
      operationId: renameClient
      description:
        <h3>Administrator renames client.</h3>
        <p>This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
      parameters:
        - in: path
          name: id
          description: id of the client
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientName'
      responses:
        '204':
          description: renaming was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /diagnostics/info/download:
    get:
      tags:
        - diagnostics
      summary: download diagnostics report
      operationId: downloadDiagnosticsReport
      description: <h3>Administrator downloads diagnostics report.</h3>
      responses:
        '200':
          description: system information
          content:
            application/json:
              schema:
                type: string
                format: binary
                description: system information file
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/globalconf:
    get:
      tags:
        - diagnostics
      summary: view global configuration diagnostics information
      operationId: getGlobalConfDiagnostics
      description: <h3>Administrator views the global configuration diagnostics information.</h3>
      responses:
        '200':
          description: global configuration diagnostics information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalConfDiagnostics'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/ocsp-responders:
    get:
      tags:
        - diagnostics
      summary: view ocsp responders diagnostics information
      operationId: getOcspRespondersDiagnostics
      description: <h3>Administrator views the ocsp responders diagnostics information.</h3>
      responses:
        '200':
          description: ocsp responders diagnostics information
          content:
            application/json:
              schema:
                type: array
                description: array of ocsp responder diagnostics objects
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/CaOcspDiagnostics'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/timestamping-services:
    get:
      tags:
        - diagnostics
      summary: view timestamping services diagnostics information
      operationId: getTimestampingServicesDiagnostics
      description: <h3>Administrator views the timestamping services diagnostics information.</h3>
      responses:
        '200':
          description: timestamping services diagnostics information
          content:
            application/json:
              schema:
                type: array
                description: array of timestamping service diagnostics objects
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/TimestampingServiceDiagnostics'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/addon-status:
    get:
      tags:
        - diagnostics
      summary: view addon services diagnostics information
      operationId: getAddOnDiagnostics
      description: <h3>Administrator views the proxy addon status diagnostics information.</h3>
      responses:
        '200':
          description: addon services diagnostics information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOnStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/backup-encryption-status:
    get:
      tags:
        - diagnostics
      summary: view backup encryption services diagnostics information
      operationId: getBackupEncryptionDiagnostics
      description: <h3>Administrator views the proxy backup encryption status diagnostics information.</h3>
      responses:
        '200':
          description: backup encryption services diagnostics information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupEncryptionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/message-log-encryption-status:
    get:
      tags:
        - diagnostics
      summary: view message log encryption and grouping services diagnostics information
      operationId: getMessageLogEncryptionDiagnostics
      description: <h3>Administrator views the proxy message log encryption and grouping diagnostics information.</h3>
      responses:
        '200':
          description: message log encryption and grouping diagnostics information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageLogEncryptionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/proxy-memory-usage-status:
    get:
      tags:
        - diagnostics
      summary: view proxy memory usage information
      operationId: getProxyMemoryUsage
      description: <h3>Administrator views the proxy memory usage information.</h3>
      responses:
        '200':
          description: proxy memory usage information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyMemoryUsageStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/auth-cert-req-status:
    get:
      tags:
        - diagnostics
      summary: view authentication certificate registration request status
      operationId: getAuthCertReqStatus
      description: <h3>Administrator views the authentication certificate registration request status.</h3>
      responses:
        '200':
          description: authentication certificate registration request status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/global-conf-status:
    get:
      tags:
        - diagnostics
      summary: view global configuration download connection status
      operationId: getGlobalConfStatus
      description: <h3>Administrator views global configuration download connection status.</h3>
      responses:
        '200':
          description: global configuration download connection status
          content:
            application/json:
              schema:
                type: array
                description: array of statuses for the global configuration download connection
                items:
                  $ref: '#/components/schemas/GlobalConfConnectionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/other-security-server-status:
    get:
      tags:
        - diagnostics
      summary: view other security server connection status
      operationId: getOtherSecurityServerStatus
      description: <h3>Administrator views the other security server connection status.</h3>
      parameters:
        - in: query
          name: protocol_type
          description: service protocol type, must be REST or SOAP
          required: true
          schema:
            type: string
            enum:
              - REST
              - SOAP
            example: REST
        - in: query
          name: client_id
          description: clientId of the current security server. <instance_id>:<member_class>:<member_code>:<subsystem_code>. Subsystem code is optional.
          example: FI:GOV:123:Subsystem
          required: true
          schema:
            type: string
            format: text
        - in: query
          name: target_client_id
          description: targetClientId of the other security server. <instance_id>:<member_class>:<member_code>:<subsystem_code>.
          example: FI:GOV:123:Subsystem
          required: true
          schema:
            type: string
            format: text
        - in: query
          name: security_server_id
          description: securityServerId of the other security server. <instance_id>:<member_class>:<member_code>:<server_code>.
          example: FI:GOV:123:DEV
          required: true
          schema:
            type: string
            format: text
      responses:
        '200':
          description: other security server connection status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /diagnostics/operational-monitoring:
    get:
      tags:
        - diagnostics
      summary: view operational information
      operationId: getOperationalDataIntervals
      description: <h3>Administrator views the Security Server's operational information on diagnostics page</h3>
      parameters:
        - in: query
          name: records_from
          description: the earliest time for the queried requests being made
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-05-15T00:00:00.001Z'
        - in: query
          name: records_to
          description: the latest time for the queried requests being made
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-05-15T00:00:00.001Z'
        - in: query
          name: interval
          description: interval in minutes the requests are divided into
          required: true
          schema:
            type: integer
            format: int32
            example: '15'
        - in: query
          name: security_server_type
          description: whether this Security Server was a 'Client' or a 'Producer'
          example: 'Client'
          required: false
          schema:
            type: string
            format: text
        - in: query
          name: member_id
          description: clientId of the Member who made or received the request. <instance_id>:<member_class>:<member_code>:<subsystem_code>. Subsystem code is optional.
          example: FI:GOV:123:Subsystem
          required: false
          schema:
            type: string
            format: text
        - in: query
          name: service_id
          description: serviceId of the Service that received the request. <instance_id>:<member_class>:<member_code>:<subsystem_code>:<service_code>.<version_number>. Version number is optional.
          example: FI:GOV:123:Subsystem:MyService.V1
          required: false
          schema:
            type: string
            format: text
      responses:
        '200':
          description: operational information to be visualized
          content:
            application/json:
              schema:
                type: array
                description: array of operational info objects
                items:
                  $ref: '#/components/schemas/OperationalDataInterval'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /initialization:
    post:
      tags:
        - initialization
      summary: Initialize a new security server with the provided initial configuration
      operationId: initSecurityServer
      description:
        <h3>Administrator initializes a new Security Server with the provided initial configuration.</h3>
        <p>
        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 <code>weak_pin</code> is used and the entries in the metadata array are always ordered in following way
        <ul>
        <li>metadata has a list of strings ["pin_min_length", x, "pin_min_char_classes_count", y] where</li>
        <li>x = the minimum length of the pin code</li>
        <li>y = the minimum amount of character classes (e.g. uppercase, number, special characters) to be used in the pin code</li>
        </ul>
        Other possible error code is <code>invalid_init_params</code> which can have any one or more of the following strings in the metadata field
        <ul>
        <li>server_code_not_provided</li>
        <li>member_class_not_provided</li>
        <li>member_code_not_provided</li>
        <li>pin_code_not_provided</li>
        <li>server_code_exists</li>
        <li>member_class_exists</li>
        <li>member_code_exists</li>
        <li>pin_code_exists</li>
        </ul>
        </p>
        <p>
        This endpoint can return a warnings response which can be ignored by setting <code>InitialServerConf.ignore_warnings</code> = true.
        If <code>InitialServerConf.ignore_warnings</code> = false, a warnings response will be returned if any one of the following conditions is true
        <ul>
        <li>server code has already been set for this Security Server (warning code <code>init_servercode_exists</code>)</li>
        <li>server owner has already been set for this Security Server(warning code <code>init_server_owner_exists</code>)</li>
        <li>software token has already been initialized in this Security Server(warning code <code>init_software_token_initialized</code>)</li>
        <li>the provided owner member is unregistered(warning code <code>init_unregistered_member</code>)</li>
        <li>the provided server id is already in use by another Security Server(warning code <code>init_server_id_exists</code>)</li>
        </ul>
        </p>
        <strong>See the '400' response examples</strong>
      requestBody:
        description: initial security server configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitialServerConf'
      responses:
        '201':
          description: security server initialized
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_invalid_init_params:
                  $ref: '#/components/examples/ErrorInvalidInitParamsMetadataExample'
                error_weak_pin:
                  $ref: '#/components/examples/ErrorWeakPinMetadataExample'
                warnings_response:
                  $ref: '#/components/examples/InitializationWarningExample'
                validation_errors_response:
                  $ref: '#/components/examples/ValidationErrorsExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /initialization/status:
    get:
      tags:
        - initialization
      summary: Check the initialization status of the Security Server
      operationId: getInitializationStatus
      description: <h3>Administrator checks the initialization status of the Security Server.</h3>
      responses:
        '200':
          description: initialization status of the Security Server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitializationStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /local-groups/{group_id}:
    get:
      tags:
        - local-groups
      summary: get local group information
      operationId: getLocalGroup
      description: <h3>Administrator views local group details.</h3>
      parameters:
        - in: path
          name: group_id
          description: id of the local group
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '200':
          description: group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocalGroup'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    patch:
      tags:
        - local-groups
      summary: update local group information
      operationId: updateLocalGroup
      description: <h3>Administrator updates the local group information.</h3>
      parameters:
        - in: path
          name: group_id
          description: id of the local group
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocalGroupDescription'
      responses:
        '200':
          description: local group modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocalGroup'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    delete:
      tags:
        - local-groups
      summary: delete local group
      operationId: deleteLocalGroup
      description: <h3>Administrator deletes the local group.</h3>
      parameters:
        - in: path
          name: group_id
          description: id of the local group
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '204':
          description: local group deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /local-groups/{group_id}/members:
    post:
      tags:
        - local-groups
      summary: add new member for the local group
      operationId: addLocalGroupMember
      description:
        <h3>Administrator adds a new member for the local group.</h3>
        <p>The new member can be an X-Road member or a subsystem.</p>
      parameters:
        - in: path
          name: group_id
          description: id of the local group
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Members'
      responses:
        '201':
          description: new members added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Members'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /local-groups/{group_id}/members/delete:
    post:
      tags:
        - local-groups
      summary: delete member from local group
      operationId: deleteLocalGroupMember
      description: <h3>Administrator deletes the member from local group.</h3>
      parameters:
        - in: path
          name: group_id
          description: id of the local group
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Members'
      responses:
        '204':
          description: members deleted
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /keys/{id}:
    get:
      tags:
        - keys
      summary: get information for the selected key in selected token
      operationId: getKey
      description: <h3>Administrator views key details.</h3>
      parameters:
        - in: path
          name: id
          description: id of the key
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '200':
          description: key object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    patch:
      tags:
        - keys
      summary: update key information
      operationId: updateKey
      description: <h3>Administrator updates the key information.</h3>
      parameters:
        - in: path
          name: id
          description: id of the key
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyName'
      responses:
        '200':
          description: key modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    delete:
      tags:
        - keys
      summary: delete key
      operationId: deleteKey
      description:
        <h3>Administrator deletes the key.</h3>
        <p>This endpoint can also return metadata in the error response if sending an auth cert deletion management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.</p>
        <p>
        Note that with this endpoint it's possible to delete an authentication key with a registered authentication certificate.
        <ul>
        <li>Attempt to delete an authentication key with a registered authentication certificate and with <code>ignore_warnings</code> = false causes the operation to fail with a warning in response's ErrorInfo object.</li>
        <li>Attempt to delete an authentication key with a registered authentication certificate and with <code>ignore_warnings</code> = true succeeds. The authentication certificate is first unregistered, and the key and certificate are deleted after that.</li>
        </ul>
        <p>When trying to delete an authentication key with a registered authentication certificate, the warning response has a warning code <code>auth_key_with_registered_cert_warning</code> and the metadata field contains the key id of the key</p>
        </p>
      parameters:
        - in: path
          name: id
          description: id of the key
          required: true
          schema:
            type: string
            format: text
            minLength: 1
        - in: query
          name: ignore_warnings
          description: if true, any ignorable warnings are ignored. if false (or missing),
            any warnings cause request to fail
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: key deletion was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                warnings_response:
                  $ref: '#/components/examples/DeleteKeyWarningExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /keys/{id}/csrs:
    post:
      tags:
        - keys
      summary: generate csr for the selected key
      operationId: generateCsr
      description: <h3>Administrator generates csr for the key.</h3>
      parameters:
        - in: path
          name: id
          description: id of the key
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        description: request to generate csr
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CsrGenerate'
            examples:
              sign_csr_example:
                $ref: '#/components/examples/SignCsrGenerateExample'
              auth_csr_example:
                $ref: '#/components/examples/AuthCsrGenerateExample'
      responses:
        '201':
          description: created CSR
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: csr file
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /keys/{id}/csrs/{csr_id}:
    get:
      tags:
        - keys
      summary: download a CSR binary
      operationId: downloadCsr
      description: <h3>Administrator downloads a csr that has been created earlier.</h3>
      parameters:
        - in: path
          name: id
          description: id of the key
          required: true
          schema:
            type: string
            format: text
            minLength: 1
        - in: path
          name: csr_id
          description: id of the csr
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 40
        - in: query
          name: csr_format
          description: format of the certificate signing request (PEM or DER)
          required: false
          schema:
            $ref: '#/components/schemas/CsrFormat'
      responses:
        '201':
          description: CSR binary
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: csr file
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    delete:
      tags:
        - keys
      summary: delete csr from the selected key
      operationId: deleteCsr
      description: <h3>Administrator deletes csr from the key.</h3>
      parameters:
        - in: path
          name: id
          description: id of the key
          required: true
          schema:
            type: string
            format: text
            minLength: 1
        - in: path
          name: csr_id
          description: id of the csr
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 40
      responses:
        '204':
          description: csr deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /keys/{id}/csrs/{csr_id}/possible-actions:
    get:
      tags:
        - keys
      summary: get possible actions for one csr
      operationId: getPossibleActionsForCsr
      description: <h3>UI needs to know which actions can be done on one csr.</h3>
      parameters:
        - in: path
          name: id
          description: id of the key
          required: true
          schema:
            type: string
            format: text
            minLength: 1
        - in: path
          name: csr_id
          description: id of the csr
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 40
      responses:
        '200':
          description: possible actions that can be done on the certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PossibleActions'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /keys/{id}/possible-actions:
    get:
      tags:
        - keys
      summary: get possible actions for one key
      operationId: getPossibleActionsForKey
      description: <h3>UI needs to know which actions can be done on one key.</h3>
      parameters:
        - in: path
          name: id
          description: id of the key
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '200':
          description: possible actions that can be done on the certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PossibleActions'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /member-classes:
    get:
      tags:
        - member-classes
      summary: get list of known member classes
      operationId: getMemberClasses
      description: <h3>Administrator lists member classes.</h3>
      parameters:
        - in: query
          name: current_instance
          description: if true, return member classes for this instance.
            if false (default), return member classes for all instances
          required: false
          schema:
            default: false
            type: boolean
      responses:
        '200':
          description: array of member classes
          content:
            application/json:
              schema:
                type: array
                description: array of member classes
                uniqueItems: true
                items:
                  type: string
                  format: text
                  minLength: 1
                  maxLength: 255
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /member-classes/{id}:
    get:
      tags:
        - member-classes
      summary: get list of known member classes for a given instance
      operationId: getMemberClassesForInstance
      description: <h3>Administrator lists member classes for a given instance.</h3>
      parameters:
        - in: path
          name: id
          description: instance id
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: array of member classes
          content:
            application/json:
              schema:
                type: array
                description: array of member classes
                uniqueItems: true
                items:
                  type: string
                  format: text
                  minLength: 1
                  maxLength: 255
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /member-names:
    get:
      tags:
        - member-names
      summary: find member name by member class and member code
      operationId: findMemberName
      description: <h3>Administrator looks up member's name.</h3>
      parameters:
        - in: query
          name: member_class
          description: class of the member
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 255
        - in: query
          name: member_code
          description: code of the member
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: name of the member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberName'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /language/{code}:
    put:
      tags:
        - language
      summary: change language
      operationId: language
      description: <h3>Administrator changes the language for the UI.</h3>
      parameters:
        - in: path
          name: code
          description: code of the language (language code)
          required: true
          schema:
            type: string
            format: text
            minLength: 2
            maxLength: 2
      responses:
        '200':
          description: language changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Language'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /openapi.yaml:
    x-style-validator-ignored: true
    get:
      tags:
        - openapi
      summary: download security server's openapi definition
      operationId: downloadOpenApi
      description: <h3>Administrator downloads the security server's OpenAPI definition.</h3>
      responses:
        '200':
          description: openapi definition
          content:
            application/x-yaml:
              schema:
                type: string
                format: binary
                description: openapi definition file
        '400':
          description: request was invalid
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /security-servers:
    get:
      tags:
        - security-servers
      summary: get all security servers
      operationId: getSecurityServers
      description: <h3>Administrator views the details of all security servers.</h3>
      parameters:
        - in: query
          name: current_server
          description: whether to only get the current server's identifier
          required: false
          schema:
            default: false
            type: boolean
      responses:
        '200':
          description: list of SecurityServer objects
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of SecurityServer objects
                items:
                  $ref: '#/components/schemas/SecurityServer'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /security-servers/{id}:
    get:
      tags:
        - security-servers
      summary: get security server information
      operationId: getSecurityServer
      description: <h3>Administrator views the details of a security server.</h3>
      parameters:
        - in: path
          name: id
          description: id of the security server
          required: true
          schema:
            type: string
            format: text
            description: <instance_id>:<member_class>:<member_code>:<security_server_code>
            example: FI:GOV:123:sserver1
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityServer'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /services/{id}:
    get:
      tags:
        - services
      summary: get service
      operationId: getService
      description: <h3>Administrator views selected service.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service
          required: true
          schema:
            type: string
            example: CS:ORG:Client:myService.v1
            format: text
            minLength: 1
            maxLength: 1279
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    patch:
      tags:
        - services
      summary: update service
      operationId: updateService
      description:
        <h3>Administrator updates the service.</h3>
        <p>
        This endpoint can return a warnings response which can be ignored by setting <code>ServiceUpdate.ignore_warnings</code> = true.
        If <code>ServiceUpdate.ignore_warnings</code> = false, it is possible to receive a warnings response from this endpoint if any one of the following conditions is true
        <ul>
        <li>SSL authentication is set to true, but https connection to the service URL fails because SSL handshake fails</li>
        <li>SSL authentication is set to true, but https connection to the service URL fails because of other errors (e.g. host unreachable)</li>
        </ul>
        </p>
      parameters:
        - in: path
          name: id
          description: id of the service
          required: true
          schema:
            type: string
            example: CS:ORG:Client:myService.v1
            format: text
            minLength: 1
            maxLength: 1279
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceUpdate'
      responses:
        '200':
          description: service modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                warnings_response:
                  $ref: '#/components/examples/UpdateServiceSslHandshakeWarningExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /services/{id}/endpoints:
    post:
      tags:
        - services
      summary: create endpoint
      operationId: addEndpoint
      description: <h3>Administrator creates a new endpoint.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service
          required: true
          schema:
            type: string
            example: CS:ORG:Client:myService.v1
            format: text
            minLength: 1
            maxLength: 1279
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Endpoint'
      responses:
        '201':
          description: endpoint added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
        '500':
          description: internal server error
  /services/{id}/service-clients:
    get:
      tags:
        - services
      summary: get service clients who have access rights for the selected service
      operationId: getServiceServiceClients
      description: <h3>Administrator views service clients who have access to the given service.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service
          required: true
          schema:
            type: string
            example: CS:ORG:Client:myService.v1
            format: text
            minLength: 1
            maxLength: 1279
      responses:
        '200':
          description: list of service clients
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of service client objects
                items:
                  $ref: '#/components/schemas/ServiceClient'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - services
      summary: add access rights to selected service for new ServiceClients
      operationId: addServiceServiceClients
      description: <h3>Adds access rights to selected service for new ServiceClients.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1279
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceClients'
            examples:
              id_array_example:
                $ref: '#/components/examples/IdArrayExample'
      responses:
        '201':
          description: access rights added
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of added service client objects
                items:
                  $ref: '#/components/schemas/ServiceClient'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /services/{id}/service-clients/delete:
    post:
      tags:
        - services
      summary: remove access to selected service from given ServiceClients
      operationId: deleteServiceServiceClients
      description: <h3>Administrator removes access to selected service from given ServiceClients.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1279
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceClients'
            examples:
              id_array_example:
                $ref: '#/components/examples/IdArrayExample'
      responses:
        '204':
          description: access right(s) deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '500':
          description: internal server error
  /endpoints/{id}:
    get:
      tags:
        - endpoints
      summary: Get an endpoint by its id
      operationId: getEndpoint
      description:
        <h3>Administrator fetches an endpoint.</h3>
      parameters:
        - in: path
          name: id
          description: id of the endpoint
          required: true
          schema:
            type: string
            example: 102
            format: text
            minLength: 1
      responses:
        '200':
          description: endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    patch:
      tags:
        - endpoints
      summary: Update an endpoint
      operationId: updateEndpoint
      description: <h3>Administrator updates an endpoint.</h3>
      parameters:
        - in: path
          name: id
          description: id of the endpoint
          required: true
          schema:
            type: string
            example: 102
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndpointUpdate'
      responses:
        '200':
          description: endpoint updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '500':
          description: internal server error
    delete:
      tags:
        - endpoints
      summary: delete endpoint
      operationId: deleteEndpoint
      description:
        <h3>Administrator removes an endpoint.</h3>
      parameters:
        - in: path
          name: id
          required: true
          description: id of the endpoint
          schema:
            type: string
            example: 102
            format: text
            minLength: 1
      responses:
        '204':
          description: endpoint deleted
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /endpoints/{id}/service-clients:
    get:
      tags:
        - endpoints
      summary: get service clients who have access rights for the selected endpoint
      operationId: getEndpointServiceClients
      description:
        <h3>Administrator views endpoints access rights.</h3>
      parameters:
        - in: path
          name: id
          description: id of the endpoint
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '200':
          description: list of access rights
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of access right objects
                items:
                  $ref: '#/components/schemas/ServiceClient'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - endpoints
      summary: add access rights for given service clients to the selected endpoint
      operationId: addEndpointServiceClients
      description:
        <h3>Administrator add access rights for a service clients to the selected endpoint.</h3>
      parameters:
        - in: path
          name: id
          description: id of the endpoint
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceClients'
            examples:
              id_array_example:
                $ref: '#/components/examples/IdArrayExample'
      responses:
        '201':
          description: access rights added
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of added service client objects
                items:
                  $ref: '#/components/schemas/ServiceClient'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /endpoints/{id}/service-clients/delete:
    post:
      tags:
        - endpoints
      summary: remove access rights from specified service clients to the selected endpoint
      operationId: deleteEndpointServiceClients
      description:
        <h3>Administrator removes access rights from a service clients to an endpoint.</h3>
      parameters:
        - in: path
          name: id
          description: id of the endpoint
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        description: Service client to be removed
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceClients'
            examples:
              id_array_example:
                $ref: '#/components/examples/IdArrayExample'
      responses:
        '204':
          description: access right(s) deleted
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /service-descriptions/{id}:
    get:
      tags:
        - service-descriptions
      summary: get service description with provided id
      operationId: getServiceDescription
      description: <h3>Administrator views a service description with a certain id.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service description
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '200':
          description: wanted service description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    patch:
      tags:
        - service-descriptions
      summary: update url or service code for the selected service description
      operationId: updateServiceDescription
      description:
        <h3>Administrator updates the selected service description.</h3>
        <p>
        This endpoint can also return metadata in the error response if updating the service description fails due to invalid URLs, already existing service description or already existing services.
        If updating the service description fails due to an invalid service URL, the error response will have the error code <code>invalid_service_url</code> and the metadata will contain a list of invalid URLs.
        If updating the service description fails due to an already existing service description, the error response will have the error code <code>url_already_exists</code> and the metadata will contain the existing URL.
        If updating the service description fails due to already existing services, the metadata array will have a more complex format. See the description of the '409' response in this endpoint.
        </p>
        <p>
        This endpoint can return a warnings response which can be ignored by setting <code>ServiceDescriptionUpdate.ignore_warnings</code> = true.
        If <code>ServiceDescriptionUpdate.ignore_warnings</code> = false, a warnings response will be returned if any one of the following conditions is true
        <ul>
        <li>WSDL or OpenAPI3 validation fails and validation warnings are returned (warning code will be either <code>wsdl_validation_warnings</code> or <code>openapi_validation_warnings</code>)</li>
        <li>existing services will be removed (warning code <code>deleting_services</code> and the warning metadata contains a list of service codes that will be removed)</li>
        <li>new services will be added (warning code <code>adding_services</code> and the warning metadata contains a list of service codes that will be added)</li>
        </ul>
        </p>
      parameters:
        - in: path
          name: id
          description: id of the service description
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceDescriptionUpdate'
      responses:
        '200':
          description: service description modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
        '400':
          description: there are warnings or errors related to the service description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                warnings_response:
                  $ref: '#/components/examples/UpdateServiceDescriptionWarningExample'
                validation_errors_response:
                  $ref: '#/components/examples/ValidationErrorsExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description:
            <h3>An existing item already exists</h3>
            <p>
            If there are existing WSDL services with the same name, the error response will include the existing services' names and the containing WSDL's URL in the metadata array.
            </p>
            <p>
            In this case the error code <code>service_already_exists</code> (WSDL) or <code>service_code_already_exists</code> (OPENAPI3) is used and the entries in the metadata array are ordered in following way
            <ul>
            <li>metadata has a list of strings [C1,U1,C2,U2....Cn,Un] where</li>
            <li>C1 = duplicate service full code</li>
            <li>U1 = URL of the existing WSDL that has the duplicate</li>
            </ul>
            </p>
            <strong>See the example</strong>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ServiceDescriptionErrorWithMetadataExample'
        '500':
          description: internal server error
    delete:
      tags:
        - service-descriptions
      summary: delete service description
      operationId: deleteServiceDescription
      description: <h3>Administrator deletes the service description.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service description
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '204':
          description: service description deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /service-descriptions/{id}/disable:
    put:
      tags:
        - service-descriptions
      summary: disable selected service description
      operationId: disableServiceDescription
      description: <h3>Administrator disables service description.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service description
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceDescriptionDisabledNotice'
      responses:
        '204':
          description: service description disabled
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /service-descriptions/{id}/enable:
    put:
      tags:
        - service-descriptions
      summary: enable selected service description
      operationId: enableServiceDescription
      description: <h3>Administrator enables service description.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service description
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '204':
          description: service description enabled
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /service-descriptions/{id}/refresh:
    put:
      tags:
        - service-descriptions
      summary: refresh selected service description
      operationId: refreshServiceDescription
      description:
        <h3>Administrator refreshes service description.</h3>
        <p>
        This endpoint can also return metadata in the error response if refreshing the service description fails due to invalid URLs, already existing service description or already existing services.
        If refreshing the service description fails due to an invalid service URL, the error response will have the error code <code>invalid_service_url</code> and the metadata will contain a list of invalid URLs.
        If refreshing the service description fails due to an already existing service description, the error response will have the error code <code>url_already_exists</code> and the metadata will contain the existing URL.
        If refreshing the service description fails due to already existing services, the metadata array will have a more complex format. See the description of the '409' response in this endpoint.
        </p>
        <p>
        This endpoint can return a warnings response which can be ignored by setting <code>IgnoreWarnings.ignore_warnings</code> = true.
        If <code>IgnoreWarnings.ignore_warnings</code> = false, a warnings response will be returned if any one of the following conditions is true
        <ul>
        <li>WSDL or OpenAPI3 validation fails and validation warnings are returned (warning code will be either <code>wsdl_validation_warnings</code> or <code>openapi_validation_warnings</code>)</li>
        <li>existing services will be removed (warning code <code>deleting_services</code> and the warning metadata contains a list of service codes that will be removed)</li>
        <li>new services will be added (warning code <code>adding_services</code> and the warning metadata contains a list of service codes that will be added)</li>
        </ul>
        </p>
      parameters:
        - in: path
          name: id
          description: id of the service description
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IgnoreWarnings'
      responses:
        '200':
          description: service description refreshed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
        '400':
          description: there are warnings or errors related to the service description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                warnings_response:
                  $ref: '#/components/examples/RefreshServiceDescriptionWarningExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description:
            <h3>An existing item already exists</h3>
            <p>
            If there are existing WSDL services with the same name, the error response will include the existing services' names and the containing WSDL's URL in the metadata array.
            </p>
            <p>
            In this case the error code <code>service_already_exists</code> (WSDL) or <code>service_code_already_exists</code> (OPENAPI3) is used and the entries in the metadata array are ordered in following way
            <ul>
            <li>metadata has a list of strings [C1,U1,C2,U2....Cn,Un] where</li>
            <li>C1 = duplicate service full code</li>
            <li>U1 = URL of the existing WSDL that has the duplicate</li>
            </ul>
            </p>
            <strong>See the example</strong>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ServiceDescriptionErrorWithMetadataExample'
        '500':
          description: internal server error
  /service-descriptions/{id}/services:
    get:
      tags:
        - service-descriptions
      summary: get services for the selected service description
      operationId: getServiceDescriptionServices
      description: <h3>Administrator views the services for the selected service description.</h3>
      parameters:
        - in: path
          name: id
          description: id of the service description
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '200':
          description: list of services
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of service objects
                items:
                  $ref: '#/components/schemas/Service'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /system/anchor:
    get:
      tags:
        - system
      summary: view the configuration anchor information
      operationId: getAnchor
      description: <h3>Administrator views the configuration anchor information.</h3>
      responses:
        '200':
          description: anchor information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Anchor'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - system
      summary: Upload a new configuration anchor file when initializing a new security server.
      operationId: uploadInitialAnchor
      description:
        <h3>Administrator uploads a new configuration anchor file in the security server's initialization phase.</h3>
        <p>
        Calls to this endpoint only succeed if a configuration anchor is not already found – meaning that <b>this endpoint can only be used when initializing a new security server</b>.
        For updating the anchor for an already initialized security server use the <code>PUT /system/anchor</code> endpoint instead.
        </p>
      requestBody:
        description: configuration anchor
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AnchorFile'
      responses:
        '201':
          description: configuration anchor uploaded
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
    put:
      tags:
        - system
      summary: Upload a configuration anchor file to replace an existing one.
      operationId: replaceAnchor
      description:
        <h3>Administrator uploads a configuration anchor file anytime after the Security Server has been initialized.</h3>
        <p>
        <b>Note that this only works if there already exists an anchor that can be replaced.</b>
        When initalizing a new Security Server, use the endpoint <code>POST /system/anchor</code> instead.
        </p>
      requestBody:
        description: configuration anchor
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AnchorFile'
      responses:
        '201':
          description: configuration anchor uploaded
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /system/anchor/previews:
    post:
      tags:
        - system
      summary: Read and the configuration anchor file and return the hash for a preview.
      operationId: previewAnchor
      description:
        <h3>Administrator wants to preview a configuration anchor file hash.</h3>
        <p>The instance of the anchor is also validated unless the <code>validate_instance</code> query parameter is explicitly set to false. The anchor will not be saved.</p>
      parameters:
        - in: query
          name: validate_instance
          description: Whether or not to validate the owner instance of the anchor.
            Set this to false explicitly when previewing an anchor in the security server initialization phase.
            Default value is true if the parameter is omitted.
          required: false
          schema:
            type: boolean
            default: true
      requestBody:
        description: configuration anchor
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AnchorFile'
      responses:
        '201':
          description: configuration anchor uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Anchor'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /system/anchor/download:
    get:
      tags:
        - system
      summary: download configuration anchor information
      operationId: downloadAnchor
      description: <h3>Administrator downloads the configuration anchor information.</h3>
      responses:
        '200':
          description: configuration anchor
          content:
            application/xml:
              schema:
                type: string
                format: binary
                description: configuration anchor file
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /system/certificate:
    get:
      tags:
        - system
      summary: view the security server certificate information
      operationId: getSystemCertificate
      description: <h3>Administrator views the security server TLS certificate information.</h3>
      responses:
        '200':
          description: certificate information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateDetails'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - system
      summary: generate a new internal TLS key and cert
      operationId: generateSystemTlsKeyAndCertificate
      description:
        <h3>Administrator generates new internal TLS key and certificate.</h3>
      responses:
        '204':
          description: tls key generated
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /system/certificate/export:
    get:
      tags:
        - system
      summary: download the security server certificate as gzip compressed tar archive
      operationId: downloadSystemCertificate
      description: <h3>Administrator downloads the security server TLS certificate.</h3>
      responses:
        '200':
          description: information fetched successfully
          content:
            application/gzip:
              schema:
                type: string
                format: binary
                description: certificate file
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /system/certificate/csr:
    post:
      tags:
        - system
      summary: generate new certificate request
      operationId: generateSystemCertificateRequest
      description: <h3>Administrator generates a new certificate request.</h3>
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DistinguishedName'
      responses:
        '201':
          description: created CSR
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: csr file
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /system/certificate/import:
    post:
      tags:
        - system
      summary: import new internal TLS certificate.
      operationId: importSystemCertificate
      description: <h3>Administrator imports a new internal TLS certificate</h3>
      requestBody:
        description: certificate to add
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CertificateFile'
      responses:
        '200':
          description: tls certificate imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateDetails'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /system/server-address:
    get:
      tags:
        - system
      operationId: getServerAddress
      summary: Get current Security Server address
      description: <h3>Administrator views Security Server address and status</h3>
      responses:
        '200':
          description: Security Server address status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityServerAddressStatus'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'

    put:
      tags:
        - system
      operationId: addressChange
      summary: Change Security Server address
      description: <h3>Administrator changes Security Server address</h3>
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityServerAddress'
      responses:
        '202':
          description: address change request submitted
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
  /system/timestamping-services:
    get:
      tags:
        - system
      summary: view the configured timestamping services
      operationId: getConfiguredTimestampingServices
      description: <h3>Administrator views the configured timestamping services.</h3>
      responses:
        '200':
          description: list of configured timestamping services
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of timestamping service objects
                items:
                  $ref: '#/components/schemas/TimestampingService'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    post:
      tags:
        - system
      summary: add a configured timestamping service
      operationId: addConfiguredTimestampingService
      description: <h3>Administrator selects a new timestamping service.</h3>
      requestBody:
        description: Timestamping service to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimestampingService'
      responses:
        '201':
          description: timestamping service created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimestampingService'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
  /system/timestamping-services/delete:
    post:
      tags:
        - system
      summary: delete configured timestamping service
      operationId: deleteConfiguredTimestampingService
      description: <h3>Administrator removes a configured timestamping service.</h3>
      requestBody:
        description: Timestamping service to delete
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimestampingService'
      responses:
        '204':
          description: timestamping service deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /system/timestamping-services/prioritization-strategy:
    get:
      tags:
        - system
      summary: get timestamping services prioritization strategy
      operationId: getTimestampingPrioritizationStrategy
      description: <h3>Administrator views the timestamping prioritization strategy.</h3>
      responses:
        '200':
          description: Timestamping prioritization strategy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrioritizationStrategy'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '500':
          description: internal server error
  /system/node-type:
    get:
      tags:
        - system
      summary: get the node type
      operationId: getNodeType
      description: <h3>Administrator views the node type</h3>
      responses:
        '200':
          description: node type information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeTypeResponse'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '500':
          description: internal server error
  /system/auth-provider-type:
    get:
      tags:
        - system
      summary: get the authentication provider type
      operationId: getAuthProviderType
      description: <h3>Administrator views the authentication provider type</h3>
      responses:
        '200':
          description: authentication provider type information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProviderTypeResponse'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '500':
          description: internal server error
  /system/version:
    get:
      tags:
        - system
      summary: get information for the system version
      operationId: systemVersion
      description: <h3>Administrator views the system version details.</h3>
      responses:
        '200':
          description: system version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionInfo'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /system/maintenance-mode:
    get:
      tags:
        - system
      summary: get information for the maintenance mode
      operationId:  maintenanceMode
      description: <h3>Administrator views the maintenance mode details.</h3>
      responses:
        '200':
          description: maintenance mode information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaintenanceMode'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /system/maintenance-mode/enable:
    put:
      tags:
        - system
      summary: enable maintenance mode of the security server
      operationId: enableMaintenanceMode
      description: <h3>Administrator enables maintenance mode of the security server.</h3>
      requestBody:
        description: Optional message about maintenance mode
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaintenanceModeMessage'
      responses:
        '204':
          description: enable maintenance mode request was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /system/maintenance-mode/disable:
    put:
      tags:
        - system
      summary: disable maintenance mode of the security server
      operationId: disableMaintenanceMode
      description: <h3>Administrator disables maintenance mode of the security server.</h3>
      responses:
        '204':
          description: disable maintenance mode request was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
  /certificate-authorities:
    get:
      tags:
        - certificate-authorities
      summary: view the approved certificate authorities
      operationId: getApprovedCertificateAuthorities
      description: <h3>Administrator views the approved certificate authorities.</h3>
      parameters:
        - in: query
          name: key_usage_type
          description: return only CAs suitable for this type of key usage
          required: false
          schema:
            $ref: '#/components/schemas/KeyUsageType'
        - in: query
          name: include_intermediate_cas
          description: if true, include also intermediate CAs. Otherwise only top CAs are included. Default value is "false".
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: list of approved certificate authorities
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of certificate authority objects
                items:
                  $ref: '#/components/schemas/CertificateAuthority'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /certificate-authorities/{ca_name}/csr-subject-fields:
    get:
      tags:
        - certificate-authorities
      summary: get description of subject DN fields for CSR
      operationId: getSubjectFieldDescriptions
      description: <h3>List DN field descriptions to collect CSR parameters</h3>
      parameters:
        - in: path
          name: ca_name
          description: common name of the CA
          example: X-Road Test CA CN
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 255
        - in: query
          name: key_id
          description: id of the key. If provided, used only for validating correct key usage
          required: false
          schema:
            type: string
            format: text
            minLength: 1
        - in: query
          name: key_usage_type
          description: which usage type this CSR is for
          required: true
          schema:
            $ref: '#/components/schemas/KeyUsageType'
        - in: query
          name: member_id
          description: member client id for signing CSRs. <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          required: false
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 767
        - in: query
          name: is_new_member
          description: whether or not the member in the member_id parameter is a new member
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: csr subject field objects
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of CsrSubjectFieldDescription objects
                items:
                  $ref: '#/components/schemas/CsrSubjectFieldDescription'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /certificate-authorities/{ca_name}/has-acme-eab-credentials:
    get:
      tags:
        - certificate-authorities
      summary: Does the member have external CA account credentials for its ACME server in the configurations.
      operationId: hasAcmeExternalAccountBindingCredentials
      description: <h3>Check whether given member has external CA account credentials for its ACME server.</h3>
        <p>Determines whether the administrator can order the certificate from ACME server with the generated CSR. The credentials are stored in the acme.yml configuration file</p>
      parameters:
        - in: path
          name: ca_name
          description: common name of the CA
          example: X-Road Test CA CN
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 255
        - in: query
          name: key_usage_type
          description: which usage type this CSR is for
          example: SIGNING
          required: true
          schema:
            $ref: '#/components/schemas/KeyUsageType'
        - in: query
          name: member_id
          description: <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          required: false
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: acme eab credentials status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcmeEabCredentialsStatus'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /certificate-authorities/{ca_name}/acme-order:
    post:
      tags:
        - certificate-authorities
      summary: order certificate from CA hosted ACME server with the given CSR
      operationId: orderAcmeCertificate
      description: <h3>Administrator orders the certificate with previously generated CSR whose certificate profile matches chosen CA-s configured profile.</h3>
      parameters:
        - in: path
          name: ca_name
          description: common name of the CA
          example: X-Road Test CA CN
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 255
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcmeOrder'
      responses:
        '200':
          description: acme certificate order was successful
        '400':
          description: request was invalid
        '403':
          description: request has been refused
        '409':
          description: an existing item already exists, outdated global conf or token not logged in
        '500':
          description: internal server error
  /certificate-authorities/ocsp-prioritization-strategy:
    get:
      tags:
        - certificate-authorities
      summary: get OCSP responders prioritization strategy
      operationId: getOcspPrioritizationStrategy
      description: <h3>Administrator views the OCSP prioritization strategy.</h3>
      responses:
        '200':
          description: OCSP prioritization strategy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrioritizationStrategy'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '500':
          description: internal server error
  /mail/mail-notification-status:
    get:
      tags:
        - mail
      summary: view status of automatic e-mail notifications
      operationId: getMailNotificationStatus
      description: <h3>Administrator views the status of sending automatic e-mail notifications sent by automatic certificate renewal job.</h3>
      responses:
        '200':
          description: e-mail notifications status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailNotificationStatus'
        '500':
          description: internal server error
  /mail/send-test-mail:
    put:
      tags:
        - mail
      summary: send test mail to the given recipient
      operationId: sendTestMail
      description: <h3>Administrator send a test e-mail to the given recipient to verify the e-mail configuration</h3>
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MailRecipient'
      responses:
        '200':
          description: test mail sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestMailResponse'
        '400':
          description: request was invalid
        '500':
          description: internal server error, that is not mail related
  /timestamping-services:
    get:
      tags:
        - timestamping-services
      summary: view the approved timestamping services
      operationId: getApprovedTimestampingServices
      description: <h3>Administrator views the approved timestamping services.</h3>
      responses:
        '200':
          description: list of approved timestamping services
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of timestamping service objects
                items:
                  $ref: '#/components/schemas/TimestampingService'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /tokens:
    get:
      tags:
        - tokens
      summary: get security server tokens
      operationId: getTokens
      description: <h3>Administrator views tokens of the security server.</h3>
      responses:
        '200':
          description: list of tokens
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of token objects
                items:
                  $ref: '#/components/schemas/Token'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /tokens/{id}:
    get:
      tags:
        - tokens
      summary: get security server token information
      operationId: getToken
      description: <h3>Administrator views the token details of the security server.</h3>
      parameters:
        - in: path
          name: id
          description: id of the token
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '200':
          description: token object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    delete:
      tags:
        - tokens
      summary: delete security server token
      operationId: deleteToken
      description: <h3>Administrator delete inactive token of the security server.</h3>
      parameters:
        - in: path
          name: id
          description: id of the token
          required: true
          schema:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
      responses:
        '204':
          description: deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: request action not possible
        '500':
          description: internal server error
    patch:
      tags:
        - tokens
      summary: update security server token information
      operationId: updateToken
      description: <h3>Administrator updates the token information.</h3>
      parameters:
        - in: path
          name: id
          description: id of the token
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenName'
      responses:
        '200':
          description: token modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /tokens/{id}/pin:
    put:
      tags:
        - tokens
      summary: update security server software token pin code
      operationId: updateTokenPin
      description:
        <h3>Administrator updates the software token pin code.</h3>
        <p>This operation supports updating the pin code of a software token only.</p>
        <p>
        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 <code>weak_pin</code> is used and the entries in the metadata array are always ordered in following way
        <ul>
        <li>metadata has a list of strings ["pin_min_length", x, "pin_min_char_classes_count", y] where</li>
        <li>x = the minimum length of the pin code</li>
        <li>y = the minimum amount of character classes (e.g. uppercase, number, special characters) to be used in the pin code</li>
        </ul>
        </p>
      parameters:
        - in: path
          name: id
          description: id of the software token
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPinUpdate'
      responses:
        '204':
          description: software token pin updated
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_weak_pin:
                  $ref: '#/components/examples/ErrorWeakPinMetadataExample'
                validation_errors_response:
                  $ref: '#/components/examples/ValidationErrorsExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /tokens/{id}/keys-with-csrs:
    post:
      tags:
        - tokens
      summary: add a new key and generate a csr for it
      operationId: addKeyAndCsr
      description:
        <h3>Administrator adds a new key and generates a csr for it.</h3>
      parameters:
        - in: path
          name: id
          description: id of the token
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyLabelWithCsrGenerate'
            examples:
              key_label_csr_example:
                $ref: '#/components/examples/KeyLabelWithCsrGenerateExample'
      responses:
        '201':
          description: key created for the token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyWithCertificateSigningRequestId'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists or token not logged in
        '500':
          description: internal server error
  /tokens/{id}/keys:
    post:
      tags:
        - tokens
      summary: add new key
      operationId: addKey
      description: <h3>Adds key for selected token.</h3>
      parameters:
        - in: path
          name: id
          description: id of the token
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyLabel'
      responses:
        '201':
          description: key created for the token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists or token not logged in
        '500':
          description: internal server error
  /tokens/{id}/login:
    put:
      tags:
        - tokens
      summary: login to token
      operationId: loginToken
      description: <h3>Administrator logs in to a token</h3>
      parameters:
        - in: path
          name: id
          description: id of the token
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenPassword'
      responses:
        '200':
          description: logged in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /tokens/{id}/logout:
    put:
      tags:
        - tokens
      summary: logout from token
      operationId: logoutToken
      description: <h3>Administrator logs out from token.</h3>
      parameters:
        - in: path
          name: id
          description: id of the token
          required: true
          schema:
            type: string
            format: text
            minLength: 1
      responses:
        '200':
          description: logged out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
  /xroad-instances:
    get:
      tags:
        - x-road-instances
      summary: get list of known x-road instance identifiers
      operationId: getXRoadInstances
      description: <h3>Administrator lists x-road instance identifiers</h3>
      responses:
        '200':
          description: x-road instance identifiers
          content:
            application/json:
              schema:
               type: array
               uniqueItems: true
               description: array of x-road instance identifiers
               items:
                 $ref: '#/components/schemas/XRoadInstance'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
components:
  examples:
    ErrorExample:
      $ref: '../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample'
    ErrorWithMetadataExample:
      $ref: '../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorWithMetadataExample'
    SignCsrGenerateExample:
      summary: Sign CSR generate request body example
      value:
        key_usage_type: SIGNING
        ca_name: Customized Test CA CN
        csr_format: DER
        member_id: CS:NIIS:1234
        subject_field_values:
          CN: something.niis.org
          C: FI
          O: NIIS
          serialNumber: CS/SS1/NIIS
    AuthCsrGenerateExample:
      summary: Auth CSR generate request body example
      value:
        key_usage_type: AUTHENTICATION
        ca_name: Customized Test CA CN
        csr_format: PEM
        subject_field_values:
          CN: something.niis.org
          C: FI
          O: NIIS
          L: Helsinki
          OU: Development
          serialNumber: CS/SS1/NIIS
    KeyLabelWithCsrGenerateExample:
      summary: Key label and CSR generate request body example 1
      value:
        key_label: My new key
        csr_generate_request:
          key_usage_type: SIGNING
          ca_name: Customized Test CA CN
          csr_format: DER
          member_id: CS:NIIS:1234
          subject_field_values:
            CN: something.niis.org
            C: FI
            O: NIIS
            serialNumber: CS/SS1/NIIS
    IdArrayExample:
      summary: Id array request body example
      value:
        items:
          - DEV:ORG:1234:Subsystem
          - DEV:security-server-owners
          - "123"
    ErrorInvalidInitParamsMetadataExample:
      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"
    ErrorWeakPinMetadataExample:
      summary: Initialization or pin change error with metadata when the provided pin is too weak
      value:
        status: 400
        error:
          code: weak_pin
          metadata:
            - "pin_min_length"
            - "8"
            - "pin_min_char_classes_count"
            - "3"
    ServiceDescriptionErrorWithMetadataExample:
      summary: Error when adding a service description and some duplicate services already exist
      value:
        status: 409
        error:
          code: service_already_exists
          metadata:
            - duplicateService.v1
            - http://xroad-lxd-cs.lxd/duplicate1.wsdl
            - anotherDuplicateService.v1
            - http://xroad-lxd-cs.lxd/duplicate1.wsdl
            - yetAnotherDuplicateService.v1
            - http://xroad-lxd-cs.lxd/someOtherWsdl.wsdl
    ValidationErrorsExample:
      summary: Validation errors response body example
      value:
        status: 400
        error:
          code: validation_failure
          validation_errors:
            "clientAdd.client.memberCode":
              - NoPercent
            "clientAdd.client.subsystemCode":
              - NoPercent
              - NoBackslashes
    RefreshServiceDescriptionWarningExample:
      summary: Warning response when refreshing a service description adds or removes services
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
          - code: adding_services
            metadata:
              - "newService.v1"
              - "anotherNewService.v1"
          - code: deleting_services
            metadata:
              - "someOldService.v1"
    UploadExistingBackupWarningExample:
      summary: Warning response when uploading a new backup configuration file with an existing name
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
          - code: warning_file_already_exists
            metadata:
              - conf_backup_20201006-094932.tar
    AddUnregisteredMemberWarningExample:
      summary: Warning response when adding a new member that has not been registered in central server
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
          - code: unregistered_member
            metadata:
              - CS/ORG/NON_EXISTING_CODE
    AddServiceDescriptionWarningExample:
      summary: Add service description warning example. The warnings metadata contains the output from the validator's
        error stream.
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
          - code: wsdl_validation_warnings
            metadata:
              - Validation failed because of...
    InitializationWarningExample:
      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
    DeleteKeyWarningExample:
      summary: Warning response when trying to delete an authentication key with a registered authentication certificate
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
          - code: auth_key_with_registered_cert_warning
            metadata:
              - 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
    UpdateServiceSslHandshakeWarningExample:
      summary: Warning response when trying to update a service with HTTPS set to "true" but the SSL handshake fails.
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
          - code: internal_server_ssl_handshake_error
    UpdateServiceDescriptionWarningExample:
      summary: Warning response when updating a service description adds or removes services
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
          - code: adding_services
            metadata:
              - "newService.v1"
              - "anotherNewService.v1"
          - code: deleting_services
            metadata:
              - "someOldService.v1"
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: X-Road-ApiKey token=<api key>
      # https://github.com/nordic-institute/X-Road-REST-UI/blob/XRDDEV-237/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md#1911-creating-new-api-keys
  schemas:
    AccessRight:
      type: object
      description: access right given for a specific subject (ServiceClient) for specific service (service_code) owned by some client. This object does not represent endpoint-level access rights
      required:
        - service_code
      properties:
        service_code:
          type: string
          format: text
          description: service code
          example: clientDeletion
          minLength: 1
          maxLength: 255
        service_title:
          type: string
          readOnly: true
          format: text
          description: service title
          example: client deletion
          minLength: 1
          maxLength: 255
        rights_given_at:
          type: string
          format: date-time
          description: access right given at
          example: '2018-12-15T00:00:00.001Z'
          readOnly: true
    AccessRights:
      type: object
      description: object containing and array of AccessRights
      properties:
        items:
          type: array
          uniqueItems: true
          description: array of AccessRights
          items:
            $ref: '#/components/schemas/AccessRight'
    AddOnStatus:
      type: object
      description: addon module statuses
      required:
        - messagelog_enabled
        - opmonitoring_enabled
      properties:
        messagelog_enabled:
          type: boolean
          readOnly: true
          description: MessageLog status
        opmonitoring_enabled:
          type: boolean
          readOnly: true
          description: OpMonitoring status
    BackupEncryptionStatus:
      type: object
      description: backup encryption statuses
      required:
        - backup_encryption_status
      properties:
        backup_encryption_status:
          type: boolean
          readOnly: true
          description: backup encryption status
        backup_encryption_keys:
          type: array
          description: backup encryption keys
          items:
            type: string
            format: text
            description: backup encryption key
    MessageLogEncryptionStatus:
      type: object
      description: message log encryption statuses
      required:
        - message_log_archive_encryption_status
        - message_log_database_encryption_status
        - message_log_grouping_rule
      properties:
        message_log_archive_encryption_status:
          type: boolean
          readOnly: true
          description: message log archive encryption status
        message_log_database_encryption_status:
          type: boolean
          readOnly: true
          description: message log database encryption status
        message_log_grouping_rule:
          type: string
          readOnly: true
          description: message log grouping rule
        members:
          type: array
          description: message log encryption members
          items:
            $ref: '#/components/schemas/MessageLogArchiveEncryptionMember'
    MessageLogArchiveEncryptionMember:
      type: object
      description: message log archive encryption member
      required:
        - member_id
      properties:
        member_id:
          type: string
          readOnly: true
          description: member id
        keys:
          type: array
          uniqueItems: true
          description: array of keys
          items:
            type: string
            format: text
          readOnly: true
        default_key_used:
          type: boolean
          readOnly: true
          description: default key used
    ProxyMemoryUsageStatus:
      type: object
      description: proxy memory usage status
      required:
        - max_memory
        - total_memory
        - used_memory
        - usage_percent
        - is_used_over_threshold
      properties:
        max_memory:
          type: number
          readOnly: true
          description: Proxy's maximum memory
        total_memory:
          type: number
          readOnly: true
          description: Proxy's total allocated memory
        used_memory:
          type: number
          readOnly: true
          description: Proxy's used memory
        threshold:
          type: number
          readOnly: true
          description: Proxy memory usage alert threshold
        usage_percent:
          type: number
          readOnly: true
          description: Proxy's used memory percentage
        is_used_over_threshold:
          type: boolean
          readOnly: true
          description: Is usage over threshold
    ConnectionStatus:
      type: object
      description: connection status
      required:
        - status_class
        - error
      properties:
        status_class:
          readOnly: true
          description: connection status class
          allOf:
            - $ref: '#/components/schemas/DiagnosticStatusClass'
        error:
          $ref: '#/components/schemas/CodeWithDetails'
    GlobalConfConnectionStatus:
      type: object
      description: global configuration download connection status
      required:
        - download_url
        - connection_status
      properties:
        download_url:
          type: string
          format: text
          minLength: 1
          maxLength: 255
          description: download url of the global configuration
        connection_status:
          $ref: '#/components/schemas/ConnectionStatus'
    XRoadInstance:
      type: object
      description: x-road instance
      required:
        - identifier
        - local
      properties:
        identifier:
          type: string
          readOnly: true
          format: text
          minLength: 1
          maxLength: 255
          description: x-road instance identifier
        local:
          type: boolean
          readOnly: true
          description: is this the local x-road instance
    MailNotificationStatus:
      type: object
      description: automatic e-mail notification status
      properties:
        enabled_notifications:
          type: array
          uniqueItems: true
          description: array containing the mail notification types that are enabled
          items:
            $ref: '#/components/schemas/MailNotificationType'
        configuration_present:
          type: boolean
          description: whether automatic e-mail has been configured
        recipients_emails:
          type: array
          description: configured recipients e-mail addresses
          items:
            type: string
            format: text
            minLength: 1
            maxLength: 255
    MailNotificationType:
      type: string
      format: enum
      description: types of mail notifications that can be turned on or off via configuration
      example: ACME_FAILURE
      enum:
        - ACME_FAILURE
        - ACME_SUCCESS
        - AUTH_CERT_REGISTERED
        - ACME_CERT_AUTOMATICALLY_ACTIVATED
        - ACME_CERT_AUTOMATIC_ACTIVATION_FAILURE
    MailRecipient:
      type: object
      required:
        - mail_address
      properties:
        mail_address:
          type: string
          description: recipient e-mail address
          format: text
          minLength: 1
          maxLength: 255
      example:
        name: member1@example.org
    TestMailResponse:
      type: object
      required:
        - status
        - text
      properties:
        status:
          $ref: '#/components/schemas/MailStatus'
        text:
          type: string
          description: A success or an error message
          format: text
    MailStatus:
      type: string
      format: enum
      description: Whether the sending was a success or an error
      example: success
      enum:
        - success # Sending mail was a success
        - error # Sending mail failed
    OperationalDataInterval:
      type: object
      description: Operational information to be visualized
      properties:
        interval_start_time:
          type: string
          format: date-time
          description: The beginning of this time window
        success_count:
          description: number of successful requests in this time window
          type: integer
          format: int64
        failure_count:
          description: number of failed requests in this time window
          type: integer
          format: int64
    Anchor:
      type: object
      description: security server anchor
      required:
        - hash
        - created_at
      properties:
        hash:
          type: string
          format: hash
          description: anchor hash
          example: 42:34:C3:22:55:42:34:C3:22:55:42:34:C3:22:55:42:34:C3:22:55:42:34:C3:22:55:42:34:C3
          minLength: 1
          maxLength: 255
        created_at:
          type: string
          format: date-time
          description: anchor created at
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
    Backup:
      type: object
      description: security server backup
      required:
        - filename
        - created_at
      properties:
        filename:
          type: string
          format: filename
          description: backup filename
          example: configuration_backup_20181224.tar
          minLength: 1
          maxLength: 255
        created_at:
          type: string
          format: date-time
          description: backup created at
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
    BackupExt:
      allOf:
        - $ref: '#/components/schemas/Backup'
      type: object
      description: security server backup with extra information
      required:
        - local_conf_present
      properties:
        local_conf_present:
          type: boolean
          description: if local configuration is present in the backup
    BackupArchive:
      type: object
      description: security server backup archive file
      properties:
        backup:
          type: string
          format: binary
          description: backup archive file
    CertificateFile:
      type: object
      description: certificate file
      properties:
        certificate:
          description: the certificate file
          format: binary
          type: string
      required:
        - certificate
    AnchorFile:
      type: object
      description: Anchor File
      properties:
        anchor:
          description: the anchor file
          format: binary
          type: string
      required:
        - anchor
    TokenCertificateSigningRequest:
      type: object
      description: CSR for certificate that is stored in a Token. Also includes the possible actions that can be
        done to this object, e.g DELETE (only for csr related operations and does not consider user authorization).
      required:
        - id
        - owner_id
        - possible_actions
      properties:
        id:
          type: string
          format: text
          description: CSR id
          example: 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
          readOnly: true
        owner_id:
          type: string
          format: text
          description: client id of the owner member, <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          minLength: 1
          maxLength: 767
          readOnly: true
        certificate_profile:
          type: string
          format: text
          description: Fully qualified class name that was used to create the CSR. Implements the ee.ria.xroad.common.certificateprofile.CertificateProfileInfoProvider interface.
          example: org.example.TestCertificateInfoProvider
          readOnly: true
        possible_actions:
          $ref: '#/components/schemas/PossibleActions'
    TokenCertificate:
      type: object
      description: Certificate that is stored in a Token (auth or sign cert). Also includes the possible actions
        that can be done to this object, e.g DELETE (only for cert related operations and does not consider
        user authorization).
      required:
        - ocsp_status
        - owner_id
        - active
        - saved_to_configuration
        - certificate_details
        - status
      properties:
        ocsp_status:
          $ref: '#/components/schemas/CertificateOcspStatus'
        owner_id:
          type: string
          format: text
          description: client id of the owner member, <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          minLength: 1
          maxLength: 767
          readOnly: true
        active:
          type: boolean
          description: if the certificate is active
          example: true
        saved_to_configuration:
          type: boolean
          description: if the certificate is saved to configuration
          example: true
        renewed_cert_hash:
          type: string
          format: text
          description: hash of the newer version of the certificate that is in the process of registration
          readOnly: true
        renewal_error:
          type: string
          format: text
          description: error message thrown during the certificate automatic renewal process
          readOnly: true
        ocsp_verify_before_activation_error:
          type: string
          format: text
          description: error message thrown when verifying ocsp responses before the certificate activation
          readOnly: true
        next_automatic_renewal_time:
          type: string
          format: date-time
          description: next planned automatic renewal time
          readOnly: true
        certificate_details:
          $ref: '#/components/schemas/CertificateDetails'
        status:
          $ref: '#/components/schemas/CertificateStatus'
        possible_actions:
          $ref: '#/components/schemas/PossibleActions'
    CaOcspDiagnostics:
      type: object
      description: Ocsp responder diagnostics
      required:
        - distinguished_name
        - ocsp_responders
      properties:
        distinguished_name:
          type: string
          format: text
          description: CA distinguished name
          example: C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
          maxLength: 255
          readOnly: true
        ocsp_responders:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/OcspResponderDiagnostics'
    CertificateDetails:
      type: object
      description: certificate details for any kind of certificate (TLS, auth, sign)
      required:
        - issuer_distinguished_name
        - issuer_common_name
        - subject_distinguished_name
        - subject_common_name
        - not_before
        - not_after
        - serial
        - version
        - signature_algorithm
        - signature
        - public_key_algorithm
        - rsa_public_key_modulus
        - rsa_public_key_exponent
        - hash
        - key_usages
        - subject_alternative_names
      properties:
        issuer_distinguished_name:
          type: string
          format: text
          description: certificate issuer distinguished name
          example: issuer123
          minLength: 1
          maxLength: 255
        issuer_common_name:
          type: string
          format: text
          description: certificate issuer common name
          example: domain.com
          minLength: 1
          maxLength: 255
        subject_distinguished_name:
          type: string
          format: text
          description: certificate subject distinguished name
          example: subject123
          minLength: 1
          maxLength: 255
        subject_common_name:
          type: string
          format: text
          description: certificate subject common name
          example: domain.com
          minLength: 1
          maxLength: 255
        not_before:
          type: string
          format: date-time
          description: certificate validity not before
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        not_after:
          type: string
          format: date-time
          description: certificate validity not after
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        serial:
          type: string
          format: text
          description: serial number
          example: '123456789'
          minLength: 1
          maxLength: 255
        version:
          type: integer
          format: int32
          example: 3
          description: version
        signature_algorithm:
          type: string
          format: sha-256
          description: certificate signature algorithm
          example: sha256WithRSAEncryption
          minLength: 1
          maxLength: 255
        signature:
          type: string
          format: text
          description: hex encoded certificate signature
          example: '30af2fdc1780...'
          minLength: 1
          maxLength: 255
        public_key_algorithm:
          type: string
          format: sha-256
          description: certificate public key algorithm
          example: 'sha256WithRSAEncryption'
          minLength: 1
          maxLength: 255
        rsa_public_key_modulus:
          type: string
          format: hex
          description: hex encoded RSA public key modulus (if RSA key)
          example: c44421d601...
          minLength: 1
          maxLength: 1000
        rsa_public_key_exponent:
          type: integer
          format: int32
          description: RSA public key exponent (if RSA key) as an integer
          example: 65537
        ec_public_parameters:
          description: EC public key curve (if EC key)
          example: 'secp256r1(1.2.840.10045.3.1.7)'
          format: text
          maxLength: 255
          minLength: 1
          type: string
        ec_public_key_point:
          description: hex encoded EC public key point (if EC key)
          example: c44421d601...
          format: hex
          maxLength: 1000
          minLength: 1
          type: string
        hash:
          type: string
          format: text
          description: certificate SHA-256 hash
          example: 1234567890ABCDEF
          minLength: 1
          maxLength: 64
        key_usages:
          type: array
          description: certificate key usage array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/KeyUsage'
        subject_alternative_names:
          type: string
          format: text
          description: certificate subject alternative names
          example: DNS:*.example.org
          minLength: 1
          maxLength: 1000
    CertificateAuthority:
      type: object
      description: approved certificate authority information. Only for top CAs.
      required:
        - name
        - subject_distinguished_name
        - issuer_distinguished_name
        - ocsp_response
        - not_after
        - top_ca
        - path
        - authentication_only
      properties:
        name:
          type: string
          format: text
          description: name of the CA, as defined in global conf. Used also as an identifier
          example: X-Road Test CA CN
          minLength: 1
          maxLength: 255
        subject_distinguished_name:
          type: string
          format: text
          description: subject distinguished name
          example: C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
          maxLength: 1024
        issuer_distinguished_name:
          type: string
          format: text
          description: issuer distinguished name
          example: C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
          maxLength: 1024
        ocsp_response:
          $ref: '#/components/schemas/CertificateAuthorityOcspResponse'
        not_after:
          type: string
          format: date-time
          description: certificate authority expires at
          example: '2099-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        top_ca:
          type: boolean
          description: if the certificate authority is top CA (instead of intermediate)
          example: true
        path:
          type: string
          format: text
          description: encoded path string from this CA to top CA
          example: C=FI, O=X-Road Test Intermediate, OU=X-Road Test CA OU, CN=X-Road Test CA CN Intermediate:C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
        authentication_only:
          type: boolean
          description: if certificate authority is limited for authentication use only
        certificate_profile_info:
          type: string
          format: text
          description: Fully qualified class name that was used to create the CSR. Implements the ee.ria.xroad.common.certificateprofile.CertificateProfileInfoProvider interface.
          example: org.example.TestCertificateInfoProvider
          minLength: 1
          maxLength: 1024
        default_csr_format:
          $ref: '#/components/schemas/CsrFormat'
        acme_capable:
          type: boolean
          description: if certificate authority supports ACME
        acme_server_ip_addresses:
          type: array
          description: ACME server IP address(es) that can be helpful in configuring the firewall rules.
          example: [ "12.34.5.6", "AB:cd:67::89" ]
          items:
            type: string
            format: text
        ocsp_responders:
          type: array
          description: list of ocsp responders for this CA
          items:
            $ref: '#/components/schemas/OcspResponder'
    CertificateStatus:
      type: string
      format: enum
      description: certificate status
      example: IN_USE
      enum:
        - SAVED
        - REGISTRATION_IN_PROGRESS
        - REGISTERED
        - DELETION_IN_PROGRESS
        - GLOBAL_ERROR
    CertificateAuthorityOcspResponse:
      type: string
      format: enum
      description: certificate authority OCSP status
      example: IN_USE
      enum:
        - NOT_AVAILABLE
        - OCSP_RESPONSE_UNKNOWN
        - OCSP_RESPONSE_GOOD
        - OCSP_RESPONSE_SUSPENDED
        - OCSP_RESPONSE_REVOKED
    CertificateOcspStatus:
      type: string
      format: enum
      description: certificate status
      example: IN_USE
      enum:
        - DISABLED
        - EXPIRED
        - OCSP_RESPONSE_UNKNOWN
        - OCSP_RESPONSE_GOOD
        - OCSP_RESPONSE_SUSPENDED
        - OCSP_RESPONSE_REVOKED
    DistinguishedName:
      type: object
      properties:
        name:
          type: string
          format: text
          description: distinguished name
          example: C=FI, O=X-Road Test, OU=X-Road Test CA OU, CN=X-Road Test CA CN
          minLength: 1
          maxLength: 255
    PossibleActions:
      type: array
      description: array containing the possible actions that can be done for this item
      items:
        $ref: '#/components/schemas/PossibleAction'
    PossibleAction:
      type: string
      format: enum
      description: an action to change state or edit token, key, cert or csr
      example: DELETE
      enum:
        - DELETE
        - ACTIVATE
        - DISABLE
        - LOGIN
        - LOGOUT
        - REGISTER
        - UNREGISTER
        - IMPORT_FROM_TOKEN
        - GENERATE_KEY
        - EDIT_FRIENDLY_NAME
        - GENERATE_AUTH_CSR
        - GENERATE_SIGN_CSR
        - TOKEN_CHANGE_PIN
        - TOKEN_DELETE
    Client:
      type: object
      description: x-road client
      required:
        - member_class
        - member_code
      properties:
        id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<subsystem>(optional).
            Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: FI:GOV:123:ABC
          minLength: 1
          maxLength: 1023
          readOnly: true
        instance_id:
          type: string
          format: text
          description: Xroad instance id. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: FI
          minLength: 1
          maxLength: 255
          readOnly: true
        member_name:
          type: string
          format: text
          description: Member name. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: FI
          readOnly: true
          minLength: 1
          maxLength: 255
        member_class:
          type: string
          format: text
          description: Member class. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: GOV
          minLength: 1
          maxLength: 255
        member_code:
          type: string
          format: text
          description: Member code. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: 123
          minLength: 1
          maxLength: 255
        subsystem_code:
          type: string
          format: text
          description: Subsystem code. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: ABC
          minLength: 1
          maxLength: 255
        subsystem_name:
          type: string
          format: text
          description: Subsystem name. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: FI
          readOnly: true
          minLength: 0
          maxLength: 255
        owner:
          type: boolean
          description: if this client is the owner member of this security server
          example: false
          readOnly: true
        has_valid_local_sign_cert:
          type: boolean
          description: if this client has a valid (registered and with good OCSP response) sign cert stored on this security server
          example: false
          readOnly: true
        is_management_services_provider:
          type: boolean
          description: if this client is management services provider
          example: false
          readOnly: true
        rename_status:
          $ref: '#/components/schemas/RenameStatus'
        connection_type:
          $ref: '#/components/schemas/ConnectionType'
        status:
          $ref: '#/components/schemas/ClientStatus'
    RenameStatus:
      type: string
      format: enum
      description: rename status
      example: NAME_SET
      readOnly: true
      enum:
        - NAME_SET
        - NAME_SUBMITTED
    ClientAdd:
      type: object
      description: Request to add client. Carries a Client and ignore warnings parameter
      required:
        - client
      properties:
        client:
          $ref: '#/components/schemas/Client'
        ignore_warnings:
          type: boolean
          default: false
          description: if true, any ignorable warnings are ignored. if false (or missing),
            any warnings cause request to fail
    ClientStatus:
      type: string
      format: enum
      description: client status
      example: REGISTERED
      readOnly: true
      enum:
        - REGISTERED
        - SAVED
        - GLOBAL_ERROR
        - REGISTRATION_IN_PROGRESS
        - DELETION_IN_PROGRESS
        - DISABLED
        - DISABLING_IN_PROGRESS
        - ENABLING_IN_PROGRESS
    CodeWithDetails:
      $ref: '../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/CodeWithDetails'
    ConnectionType:
      type: string
      format: enum
      description: connection type
      example: HTTP
      default: HTTPS
      enum:
        - HTTP
        - HTTPS
        - HTTPS_NO_AUTH
    ConnectionTypeWrapper:
      type: object
      description: connection type
      properties:
        connection_type:
          $ref: '#/components/schemas/ConnectionType'
    CsrFormat:
      type: string
      format: enum
      description: format of the certificate signing request (PEM or DER)
      example: PEM
      default: PEM
      enum:
        - PEM
        - DER
    CsrGenerate:
      type: object
      description: request to generate a CSR
      required:
        - key_usage_type
        - ca_name
        - csr_format
        - subject_field_values
      properties:
        key_usage_type:
          $ref: '#/components/schemas/KeyUsageType'
        ca_name:
          type: string
          format: text
          description: common name of the CA
          example: X-Road Test CA CN
          minLength: 1
          maxLength: 255
        csr_format:
          $ref: '#/components/schemas/CsrFormat'
        member_id:
          type: string
          format: text
          description: member client id for signing CSRs. <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          minLength: 1
          maxLength: 767
        subject_field_values:
          type: object
          description: user-provided values for subject DN parameters
          additionalProperties:
            type: string
        acme_order:
          type: boolean
          default: false
          description: whether or not order certificate from acme server with the generated csr
    AcmeOrder:
      type: object
      description: request to order certificate with the given CSR for the given usage type
      required:
        - csr_id
        - key_usage_type
      properties:
        csr_id:
          type: string
          format: text
          description: id of the CSR
          minLength: 1
          maxLength: 40
        key_usage_type:
          $ref: '#/components/schemas/KeyUsageType'
    AcmeEabCredentialsStatus:
      type: object
      description: Whether there are credentials in the configuration for the given Member and CA. Used for binding the CA external account with the ACME server's account.
      required:
        - has_acme_external_account_credentials
        - acme_eab_required
      properties:
        acme_eab_required:
          type: boolean
          description: if certificate authority required external account binding for ACME
        has_acme_external_account_credentials:
          type: boolean
          description: whether there are credentials present in the configuration.
          example: true
          readOnly: true
    CsrSubjectFieldDescription:
      type: object
      description: object describing input fields for CSR subject DN info
      required:
        - id
        - localized
        - read_only
        - required
      properties:
        id:
          type: string
          format: text
          description: the identifier of the field (such as 'O', 'OU' etc)
          example: O
          minLength: 1
          readOnly: true
        label:
          type: string
          format: text
          description: label of the field, used to display the field in the user interface
          example: ORGANIZATION_NAME
          minLength: 1
          readOnly: true
        label_key:
          type: string
          format: text
          description: localization key for label of the field, used to display the field in the user interface
          example: Organization name (O)
          minLength: 1
          readOnly: true
        default_value:
          type: string
          format: text
          description: the default value of the field. Can be empty.
          example: 1234
          minLength: 0
          readOnly: true
        read_only:
          type: boolean
          description: if this field is read-only
          example: true
          readOnly: true
        required:
          type: boolean
          description: if this field is required to be filled
          example: true
          readOnly: true
        localized:
          type: boolean
          description: if true, label key is in property "label_key". If false, actual label is in property "label"
          example: true
          readOnly: true
    DiagnosticStatusClass:
      type: string
      format: enum
      description: diagnostics status class
      example: OK
      enum:
        - OK
        - WAITING
        - FAIL
    ErrorInfo:
      $ref: '../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo'
    InitialServerConf:
      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
    LocalGroup:
      type: object
      description: group
      required:
        - code
        - description
      properties:
        id:
          type: string
          format: text
          description: unique identifier
          example: 123
          readOnly: true
        code:
          type: string
          format: text
          description: group code
          example: groupcode
          minLength: 1
          maxLength: 255
        description:
          type: string
          format: text
          description: group description
          example: description
          minLength: 1
          maxLength: 255
        client_id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<subsystem>(optional)
          example: FI:GOV:123:ABC
          readOnly: true
          minLength: 1
          maxLength: 255
        member_count:
          type: integer
          format: int32
          description: member count
          example: 10
          minimum: 0
          maximum: 1000000
        updated_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        members:
          type: array
          description: group members
          uniqueItems: true
          items:
            $ref: '#/components/schemas/GroupMember'
    LocalGroupAdd:
      type: object
      description: model for adding a new LocalGroup
      required:
        - code
        - description
      properties:
        code:
          type: string
          format: text
          description: group code
          example: groupcode
          minLength: 1
          maxLength: 255
        description:
          type: string
          format: text
          description: group description
          example: description
          minLength: 1
          maxLength: 255
    LocalGroupDescription:
      type: object
      required:
        - description
      properties:
        description:
          type: string
          description: description for the LocalGroup
          format: text
          minLength: 1
          maxLength: 255
      example:
        name: This is an awesome local group!
    GlobalConfDiagnostics:
      type: object
      description: global configuration diagnostics
      required:
        - status_class
        - prev_update_at
        - next_update_at
      properties:
        status_class:
          readOnly: true
          description: diagnostics status class
          allOf:
            - $ref: '#/components/schemas/DiagnosticStatusClass'
        prev_update_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        next_update_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        last_successful_url:
          type: string
          format: uri
          description: last successful configuration source URL
          example: https://example.org/configuration
          minLength: 1
          maxLength: 255
          readOnly: true
        error:
          $ref: '#/components/schemas/CodeWithDetails'
    GroupMember:
      type: object
      description: group member
      required:
        - id
        - member_name
        - created_at
      properties:
        id:
          type: string
          format: text
          description: group member id
          example: FI:GOV:123
          minLength: 1
          maxLength: 1023
        member_name:
          type: string
          format: text
          description: group member name
          example: Member123
          minLength: 1
          maxLength: 255
        subsystem_name:
          type: string
          format: text
          description: group subsystem name
          example: Subsystem123
          minLength: 0
          maxLength: 255
        created_at:
          type: string
          format: date-time
          description: group member created at
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
    IgnoreWarnings:
      type: object
      properties:
        ignore_warnings:
          type: boolean
          default: false
          description: if true, any ignorable warnings are ignored. if false (or missing),
            any warnings cause request to fail
    InitializationStatus:
      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'
        enforce_token_pin_policy:
          type: boolean
          description: whether the token pin policy is enforced or not
    KeyWithCertificateSigningRequestId:
      type: object
      description: Key and TokenCertificateSigningRequest id
      required:
        - key
        - csr_id
      properties:
        key:
          $ref: '#/components/schemas/Key'
        csr_id:
          type: string
          format: text
          description: CSR id
          example: 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
    Key:
      type: object
      description: Key for the certificate. Also includes the possible actions that can be done to this object,
        e.g DELETE (only for key related operations and does not consider user authorization).
      required:
        - id
        - name
        - label
        - certificates
        - certificate_signing_requests
        - key_algorithm
      properties:
        id:
          type: string
          format: text
          description: key id
          example: 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
          minLength: 1
          readOnly: true
        name:
          type: string
          format: text
          description: key name
          example: friendly name
          minLength: 1
          maxLength: 255
        label:
          type: string
          format: text
          description: key label
          example: key label
          minLength: 1
          maxLength: 255
        certificates:
          type: array
          description: list of certificates for the key
          items:
            $ref: '#/components/schemas/TokenCertificate'
        certificate_signing_requests:
          type: array
          description: list of CSRs for the key
          items:
            $ref: '#/components/schemas/TokenCertificateSigningRequest'
        usage:
          $ref: '#/components/schemas/KeyUsageType'
        available:
          type: boolean
          description: if the key is available
          example: true
        saved_to_configuration:
          type: boolean
          description: if the key is saved to configuration
          example: true
        possible_actions:
          $ref: '#/components/schemas/PossibleActions'
        key_algorithm:
          $ref: '#/components/schemas/KeyAlgorithm'
    KeyAlgorithm:
      description: Key type
      enum:
        - RSA
        - EC
      example: RSA
      format: enum
      type: string
    KeyName:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Friendly name of a key
          format: text
          minLength: 1
          maxLength: 255
      example:
        name: my-key-0
    KeyLabel:
      type: object
      properties:
        label:
          type: string
          format: text
          description: label for the new key
          minLength: 1
          maxLength: 255
      example:
        label: My new key
    KeyLabelWithCsrGenerate:
      type: object
      required:
        - key_label
        - csr_generate_request
      properties:
        key_label:
          type: string
          format: text
          description: label for the new key
          minLength: 0
          maxLength: 255
          example: My new key
        csr_generate_request:
          $ref: '#/components/schemas/CsrGenerate'
    KeyUsage:
      type: string
      format: enum
      description: certificate key usage
      example: NON_REPUDIATION
      enum:
        - DIGITAL_SIGNATURE
        - NON_REPUDIATION
        - KEY_ENCIPHERMENT
        - DATA_ENCIPHERMENT
        - KEY_AGREEMENT
        - KEY_CERT_SIGN
        - CRL_SIGN
        - ENCIPHER_ONLY
        - DECIPHER_ONLY
    KeyUsageType:
      type: string
      format: enum
      description: intended usage for the key (signing or authentication)
      example: AUTHENTICATION
      enum:
        - AUTHENTICATION
        - SIGNING
    KeyValuePair:
      type: object
      description: key-value pair of strings
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: key
        value:
          type: string
          description: value
    Language:
      type: object
      description: language
      required:
        - id
      properties:
        id:
          type: string
          format: text
          description: language code
          example: en
          minLength: 2
          maxLength: 2
          readOnly: true
    MemberName:
      type: object
      description: member's name
      properties:
        member_name:
          type: string
          format: text
          description: member's name
    Members:
      type: object
      description: Request object containing an array of member ids. The id must be an X-Road member id or subsystem id
      properties:
        items:
          type: array
          description: array of members to be added
          example: ["FI:GOV:123", "FI:GOV:123:SS1", "FI:GOV:123:SS2"]
          items:
            type: string
            format: text
            minLength: 1
            maxLength: 1023
    NodeType:
      type: string
      format: enum
      description:
        <p>The enum can have three different values</p>
        <ul>
        <li>PRIMARY, which is the primary node in a high availability setup</li>
        <li>SECONDARY, which is a secondary node in a high availability setup – a read-only server</li>
        <li>STANDALONE,when there are no load balancer or high availability configured</li>
        </ul>
      example: PRIMARY
      enum:
        - PRIMARY
        - SECONDARY
        - STANDALONE
    NodeTypeResponse:
      type: object
      description: Response object containing the node type of the Security Server
      required:
        - node_type
      properties:
        node_type:
          $ref: '#/components/schemas/NodeType'
    AuthProviderType:
      type: string
      format: enum
      description:
        <p>The enum can have three different values</p>
        <ul>
        <li>PAM</li>
        <li>DATABASE</li>
        </ul>
      example: PAM
      enum:
        - PAM
        - DATABASE
    AuthProviderTypeResponse:
      type: object
      description: Response object containing the authentication provider type of the Security Server
      required:
        - auth_provider_type
      properties:
        auth_provider_type:
          $ref: '#/components/schemas/AuthProviderType'
    OcspResponder:
      type: object
      description: OCSP responder
      required:
        - url
        - cost_type
      properties:
        url:
          type: string
          format: url
          description: url of the OCSP responder
          example: http://dev.xroad.rocks:123
          minLength: 1
          maxLength: 255
          readOnly: true
        cost_type:
          $ref: '#/components/schemas/CostType'
    OcspResponderDiagnostics:
      type: object
      description: OCSP responder diagnostics
      required:
        - url
        - status_class
        - next_update_at
      properties:
        url:
          type: string
          format: url
          description: url of the OCSP responder
          example: http://dev.xroad.rocks:123
          minLength: 1
          maxLength: 255
          readOnly: true
        cost_type:
          $ref: '#/components/schemas/CostType'
        status_class:
          $ref: '#/components/schemas/DiagnosticStatusClass'
        prev_update_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        next_update_at:
          type: string
          format: date-time
          description: next time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        error:
          $ref: '#/components/schemas/CodeWithDetails'
    OrphanInformation:
      type: object
      properties:
        orphans_exist:
          type: boolean
          default: false
          description: whether or not orphans exist in the database
    SecurityServer:
      type: object
      description: security server information
      required:
        - id
      properties:
        id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<security_server_code>
          example: FI:GOV:123:sserver1
        instance_id:
          type: string
          format: text
          description: xroad instance id
          example: FI
          minLength: 1
          maxLength: 255
        member_class:
          type: string
          format: text
          description: member class
          example: GOV
          minLength: 1
          maxLength: 255
        member_code:
          type: string
          format: text
          description: member code
          example: 123
          minLength: 1
          maxLength: 255
        server_code:
          type: string
          format: text
          description: security server code
          example: server123
          minLength: 1
          maxLength: 255
        server_address:
          type: string
          format: text
          description: security server address (ip or name)
          example: 192.168.1.100
          maxLength: 255
    MaintenanceModeMessage:
      type: object
      properties:
        message:
          type: string
          description: optional message describing maintenance mode
          format: text
          maxLength: 255
      example:
        message: End on 14. May
    MaintenanceMode:
      allOf:
        - $ref: '#/components/schemas/MaintenanceModeMessage'
      type: object
      properties:
        status:
          $ref: '#/components/schemas/MaintenanceModeStatus'
        is_management_services_provider:
          type: boolean
          description: is this Security server provider of management services
          example: false
          readOnly: true
      required:
        - status
        - is_management_services_provider
      example:
        status: ENABLED_MAINTENANCE_MODE
        message: End on 14. May
        is_management_services_provider: false
    MaintenanceModeStatus:
      type: string
      format: enum
      description: Maintenance Mode status
      example: ENABLED_MAINTENANCE_MODE
      enum:
        - PENDING_ENABLE_MAINTENANCE_MODE # Successful enable maintenance mode request was made and waiting for global configuration refresh
        - ENABLED_MAINTENANCE_MODE # Maintenance mode enabled
        - PENDING_DISABLE_MAINTENANCE_MODE # Successful disable maintenance mode request was made and waiting for global configuration refresh
        - DISABLED_MAINTENANCE_MODE # Maintenance mode disabled
    SecurityServerAddress:
      type: object
      required:
        - address
      properties:
        address:
          type: string
          description: Security server's IP address or DNS name
          format: text
          minLength: 1
          maxLength: 255
      example:
        address: 127.0.0.1
    ClientName:
      type: object
      required:
        - client_name
      properties:
        client_name:
          type: string
          description: Client name. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          format: text
          minLength: 1
          maxLength: 255
      example:
        client_name: Subsystem Name
    SecurityServerAddressStatus:
      type: object
      description: Security Server address with status
      properties:
        current_address:
          $ref: '#/components/schemas/SecurityServerAddress'
        requested_change:
          $ref: '#/components/schemas/SecurityServerAddress'
    Service:
      type: object
      description: service for the service description
      required:
        - id
        - service_code
        - url
        - timeout
        - service_description_id
        - client_id
      properties:
        id:
          type: string
          format: text
          description: encoded service id, including client id
          example: CS:ORG:Client:myService.v1
          minLength: 1
          maxLength: 1279
        service_description_id:
          type: string
          description: unique identifier
          example: 123
        client_id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<subsystem>(optional)
          example: FI:GOV:123:ABC
          minLength: 1
          maxLength: 255
        full_service_code:
          type: string
          format: text
          description: encoded service code and version
          example: myService.v1
          minLength: 1
          maxLength: 511
        service_code:
          type: string
          format: text
          description: encoded service code
          example: myService
          minLength: 1
          maxLength: 255
        timeout:
          type: integer
          format: int32
          description: service time out value
          example: 60
          minimum: 0
          maximum: 1000
        title:
          type: string
          readOnly: true
          format: text
          description: service title
          example: client deletion
          minLength: 1
          maxLength: 255
        ssl_auth:
          type: boolean
          description: service ssl auth
          example: true
        subjects_count:
          type: integer
          format: int32
          description: count of acl subjects
          example: 5
          minimum: 0
          maximum: 100000
        url:
          type: string
          format: url
          description: service url
          example: https://domain.com/service
          minLength: 1
          maxLength: 255
        endpoints:
          type: array
          description: list of endpoints linked to this service
          items:
            $ref: '#/components/schemas/Endpoint'
    ServiceUpdate:
      type: object
      description: object for updating a service or all services within service description
      required:
        - url
        - timeout
        - ssl_auth
      properties:
        url:
          type: string
          format: url
          description: service url
          example: https://domain.com/service
          minLength: 1
          maxLength: 255
        timeout:
          type: integer
          format: int32
          description: service time out value
          example: 60
          minimum: 0
          maximum: 1000
        ssl_auth:
          type: boolean
          description: service ssl auth
          example: true
        url_all:
          description: url is applied for all services
          type: boolean
          example: false
          default: false
        timeout_all:
          description: timeout value is applied for all services
          type: boolean
          example: false
          default: false
        ssl_auth_all:
          description: ssl authentication is applied for all services
          type: boolean
          example: false
          default: false
        ignore_warnings:
          type: boolean
          default: false
          description: if true, any ignorable warnings are ignored. if false (or missing),
            any warnings cause request to fail
    Endpoint:
      type: object
      description: Endpoint for a service
      required:
        - service_code
        - method
        - path
      properties:
        id:
          type: string
          description: unique identifier
          example: 15
        service_code:
          type: string
          example: example_service_code
          description: service code
        client_id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<subsystem>(optional)
          example: FI:GOV:123:ABC
          readOnly: true
          minLength: 1
          maxLength: 255
        method:
          type: string
          description: http method mapped to this endpoint
          example: 'GET'
          enum: [ '*', 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE' ]
        path:
          type: string
          description: relative path where this endpoint is mapped to
          example: '/foo'
        generated:
          type: boolean
          description: has endpoint been generated from openapi3 description
          example: true
          readOnly: true
    EndpointUpdate:
      type: object
      description: Object for updating endpoints method and/or path
      required:
        - method
        - path
      properties:
        method:
          type: string
          description: http method mapped to this endpoint
          example: 'GET'
          enum: [ '*', 'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE' ]
        path:
          type: string
          description: relative path where this endpoint is mapped to
          example: '/foo'
    ServiceClient:
      type: object
      description: service client. May be a subsystem, local group, or a global group
      required:
        - id
      properties:
        id:
          type: string
          format: text
          description: subject id - can be a subsystem id <instance_id>:<member_class>:<member_code>:<subsystem> | globalgroup id <instance_id>:<group_code> | localgroup resource id in number format <id>
          example: DEV:ORG:1234:Subsystem | DEV:security-server-owners | 123
          minLength: 1
          maxLength: 1279
        name:
          type: string
          format: text
          description: name of the ServiceClient - can be the name of a member or the description of a group
          example: Security server owners
          readOnly: true
          minLength: 1
          maxLength: 255
        local_group_code:
          type: string
          format: text
          description: group code in case the object is a local group
          example: My own Local group code
          minLength: 1
          maxLength: 255
          readOnly: true
        service_client_type:
          $ref: '#/components/schemas/ServiceClientType'
        rights_given_at:
          type: string
          format: date-time
          description: time when access right were given at. When listing client's service clients without specifying the service, the time when first service access right was given to this service client for any service. When listing service clients for a specific service, time when service client was added permission to that service.
          example: '2018-12-15T00:00:00.001Z'
          readOnly: true
    ServiceClients:
      type: object
      description: object containing and array of ServiceClients
      properties:
        items:
          type: array
          uniqueItems: true
          description: array of ServiceClients
          items:
            $ref: '#/components/schemas/ServiceClient'
    ServiceDescription:
      type: object
      description: WSDL/OPENAPI3/REST service
      required:
        - id
        - url
        - type
        - disabled
        - disabled_notice
        - refreshed_at
        - services
        - client_id
      properties:
        id:
          type: string
          description: unique identifier
          example: 123
        url:
          type: string
          format: url
          description: service url
          example: http://dev.xroad.rocks/services.wsdl
          minLength: 1
          maxLength: 255
        type:
          $ref: '#/components/schemas/ServiceType'
        disabled:
          type: boolean
          description: service disabled
          example: true
        disabled_notice:
          type: string
          format: text
          description: disabled notice
          example: default_disabled_service_notice
          minLength: 0
          maxLength: 255
        refreshed_at:
          type: string
          format: date-time
          description: time for service refresh
          example: "2018-12-15T00:00:00.001Z"
          minLength: 24
          maxLength: 24
        services:
          type: array
          description: service description services
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Service'
        client_id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<subsystem>(optional)
          example: FI:GOV:123:ABC
          minLength: 1
          maxLength: 255
    ServiceDescriptionAdd:
      type: object
      description: request object containing service description url, service code and type
      required:
        - url
        - type
      properties:
        url:
          type: string
          format: text
          description: path for the service description file
          example: https://domain.com/service
          minLength: 1
          maxLength: 255
        rest_service_code:
          type: string
          format: text
          description: service code for REST service
          example: exampleServiceCode
          minLength: 1
          maxLength: 255
        ignore_warnings:
          type: boolean
          description: if true, any ignorable warnings are ignored. if false (or missing),
            any warnings cause request to fail
          default: false
        type:
          $ref: '#/components/schemas/ServiceType'
    ServiceDescriptionDisabledNotice:
      type: object
      properties:
        disabled_notice:
          type: string
          format: text
          description: disabled service notice
          minLength: 0
          maxLength: 255
    ServiceDescriptionUpdate:
      type: object
      description: request object for updating a service description url or service code
      required:
        - type
        - url
      properties:
        url:
          type: string
          format: text
          description: path for the service description file
          example: https://domain.com/service
          minLength: 1
          maxLength: 255
        rest_service_code:
          type: string
          format: text
          description: service code for REST service
          example: exampleServiceCode
          minLength: 1
          maxLength: 255
        new_rest_service_code:
          type: string
          format: test
          description: new service code for REST service
          example: newExampleServiceCode
          minLength: 1
          maxLength: 255
        ignore_warnings:
          type: boolean
          description: if true, any ignorable warnings are ignored. if false (or missing),
            any warnings cause request to fail
          default: false
        type:
          $ref: '#/components/schemas/ServiceType'
    ServicePrioritizationStrategy:
      type: string
      format: enum
      description: service prioritization strategy
      example: FREE_FIRST
      enum:
        - ONLY_FREE
        - ONLY_PAID
        - FREE_FIRST
        - PAID_FIRST
        - NONE
    ServiceType:
      type: string
      format: text
      description: service type
      example: WSDL
      enum:
        - WSDL
        - REST
        - OPENAPI3
    ServiceClientType:
      type: string
      format: text
      description: subject type
      example: GLOBALGROUP
      readOnly: true
      enum:
        - GLOBALGROUP
        - LOCALGROUP
        - SUBSYSTEM
    TimestampingService:
      type: object
      description: timestamping services
      required:
        - name
        - url
        - cost_type
      properties:
        name:
          type: string
          format: text
          description: name of the time stamping service
          example: X-Road Test TSA CN
          minLength: 1
          maxLength: 255
        url:
          type: string
          format: url
          description: url of the time stamping service
          example: http://dev.xroad.rocks:123
          minLength: 1
          maxLength: 255
        cost_type:
          $ref: '#/components/schemas/CostType'
    TimestampingServiceDiagnostics:
      type: object
      description: timestamping service diagnostics
      required:
        - url
        - status_class
        - prev_update_at
      properties:
        url:
          type: string
          format: url
          description: url of the time stamping service
          example: http://dev.xroad.rocks:123
          minLength: 1
          maxLength: 255
          readOnly: true
        cost_type:
          $ref: '#/components/schemas/CostType'
        status_class:
          $ref: '#/components/schemas/DiagnosticStatusClass'
        prev_update_at:
          type: string
          format: date-time
          description: last time updated
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
          readOnly: true
        error:
          $ref: '#/components/schemas/CodeWithDetails'
    CostType:
      description: cost type for services like TSP-s and OCSP responders
      enum:
        - FREE
        - PAID
        - UNDEFINED
      example: FREE
      format: enum
      type: string
    Token:
      type: object
      description: Token. Also includes the possible actions that can be done to this object,
        e.g DELETE (only for token related operations and does not consider user authorization).
      required:
        - id
        - name
        - type
        - keys
        - status
        - logged_in
        - available
        - saved_to_configuration
        - read_only
      properties:
        id:
          type: string
          format: text
          description: token id
          example: 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
          minLength: 1
          readOnly: true
        name:
          type: string
          format: text
          description: token name
          example: softToken-0
          minLength: 1
          maxLength: 255
        type:
          $ref: '#/components/schemas/TokenType'
        keys:
          type: array
          description: token keys
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Key'
        status:
          $ref: '#/components/schemas/TokenStatus'
        logged_in:
          type: boolean
          description: if the token has been logged in to
          example: true
        available:
          type: boolean
          description: if the token is available
          example: true
        saved_to_configuration:
          type: boolean
          description: if the token is saved to configuration
          example: true
        read_only:
          type: boolean
          description: if the token is read-only
          example: true
        serial_number:
          type: string
          format: text
          description: serial number of the token
          example: 12345
        token_infos:
          type: array
          description: Contains label-value pairs of information
          items:
            $ref: '#/components/schemas/KeyValuePair'
        possible_actions:
          $ref: '#/components/schemas/PossibleActions'
    TokenInitStatus:
      type: string
      format: enum
      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
    TokenName:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: friendly name of the token
          format: text
          minLength: 1
          maxLength: 255
      example:
        name: my-token-0
    TokenPinUpdate:
      type: object
      required:
        - old_pin
        - new_pin
      properties:
        old_pin:
          type: string
          description: the old pin code of the token
          format: text
          minLength: 1
          maxLength: 255
        new_pin:
          type: string
          description: the new pin code of the token
          format: text
          minLength: 1
          maxLength: 255
      example:
        old_pin: 0000
        new_pin: 1234
    TokensLoggedOut:
      description: response that tells if hsm tokens were logged out during the restore process
      type: object
      properties:
        hsm_tokens_logged_out:
          description: whether any hsm tokens were logged out during the restore process
          type: boolean
          default: false
    TokenPassword:
      type: object
      properties:
        password:
          type: string
          format: text
          description: password for logging in to the token
          minLength: 1
      example:
        password: sm3!!ycat
    TokenStatus:
      type: string
      format: text
      description: token type
      example: OK
      enum:
        - OK # Normal operation status
        - USER_PIN_LOCKED # Blocked
        - USER_PIN_INCORRECT # Incorrect PIN was entered
        - USER_PIN_INVALID # Invalid PIN
        - USER_PIN_EXPIRED # PIN expired
        - USER_PIN_COUNT_LOW # Only a few tries left
        - USER_PIN_FINAL_TRY # Final try
        - NOT_INITIALIZED # Not inited
    TokenType:
      type: string
      format: text
      description: token type
      example: SOFTWARE
      enum:
        - SOFTWARE
        - HARDWARE
    User:
      $ref: '../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/User'
    VersionInfo:
      type: object
      description: version information
      required:
        - info
        - java_version
        - min_java_version
        - max_java_version
        - using_supported_java_version
        - java_vendor
        - java_runtime_version
      properties:
        info:
          type: string
          format: text
          description: information about the security server
          example: Security Server version 6.21.0-SNAPSHOT-20190411git32add470
          minLength: 1
          maxLength: 255
        java_version:
          type: integer
          description: java version currently in use
        min_java_version:
          type: integer
          description: minimum supported java version
        max_java_version:
          type: integer
          description: maximum supported java version
        using_supported_java_version:
          type: boolean
          description: true if currently used java version is supported
        java_vendor:
          type: string
          description: java vendor string from java.vendor system property
        java_runtime_version:
          type: string
          description: java runtime version string from java.runtime.version system property
        global_configuration_version:
          type: integer
          description: global configuration version
security:
  - ApiKeyAuth: []