X-Road (NIIS) Management Requests API

openapi: 3.2.0
info:
  title: X Road Global Management Requests API
  version: 1.0.0
  contact:
    email: info@niis.org
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged management-requests across 2 of this provider''s published API definitions: central-server-admin-openapi.yaml, x-road-global-central-server-admin-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: basepath for API v1
  url: /api/v1
security:
- ApiKeyAuth: []
tags:
- name: management-requests
  description: resources related to management requests
paths:
  /management-requests:
    get:
      tags:
      - management-requests
      summary: Find management requests
      operationId: findManagementRequests
      description: List management requests
      parameters:
      - in: query
        name: filter
        description: "optional filtering parameters. Filtering is possible according to one of the following values: <ul>\n    <li><b>q</b> Free text query</li>\n    <li><b>origin</b> Request origin</li>\n    <li><b>type</b> an array of types</li>\n    <li><b>serverId</b> Security server id</li>\n</ul>\n"
        required: false
        schema:
          $ref: '#/components/schemas/ManagementRequestsFilter'
      - in: query
        name: paging_sorting
        description: "optional paging and sorting parameters. Sorting possible according to one of the following values: <ul>\n    <li><b>id</b> for id</li>\n    <li><b>created_at</b> Creation date</li>\n</ul>\n"
        required: false
        schema:
          $ref: '#/components/schemas/PagingSortingParameters'
      responses:
        '200':
          description: array of management requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedManagementRequests'
        '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:
      - management-requests
      summary: Add a management request
      operationId: addManagementRequest
      description: Add management request
      requestBody:
        description: management request to add
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagementRequest'
      responses:
        '201':
          description: The request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagementRequest'
        '202':
          description: The request was accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagementRequest'
        '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 can not be processed due to data integrity or business rule violations
        '500':
          description: internal server error
    servers:
    - description: basepath for API v1
      url: /api/v1
  /management-requests/{management_request_id}:
    parameters:
    - $ref: '#/components/parameters/ManagementRequestIdParam'
    get:
      tags:
      - management-requests
      summary: get management request details
      operationId: getManagementRequest
      description: Administrator creates a management request
      responses:
        '200':
          description: The management request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagementRequestDetailedView'
        '400':
          description: invalid request
        '401':
          description: not authenticated
        '403':
          description: not authorized
    delete:
      tags:
      - management-requests
      summary: Revoke/decline a management request
      operationId: revokeManagementRequest
      description: Administrator revokes a management request
      responses:
        '204':
          description: Revoke succeeded
        '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
    servers:
    - description: basepath for API v1
      url: /api/v1
  /management-requests/{management_request_id}/approval:
    post:
      tags:
      - management-requests
      summary: approve a management request
      operationId: approveManagementRequest
      description: Administrator approves a management request
      parameters:
      - $ref: '#/components/parameters/ManagementRequestIdParam'
      responses:
        '200':
          description: The management request was approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagementRequest'
        '400':
          description: invalid request
        '401':
          description: not authenticated
        '403':
          description: not authorized
        '404':
          description: request not found
        '409':
          description: request can not be approved in this state
    servers:
    - description: basepath for API v1
      url: /api/v1
components:
  schemas:
    ManagementRequestDetailedView:
      type: object
      description: Management Request detailed view
      allOf:
      - $ref: '#/components/schemas/ManagementRequestListView'
      properties:
        comments:
          type: string
          format: text
        certificate_details:
          $ref: '#/components/schemas/CertificateDetails'
    ManagementRequestsFilter:
      description: parameters for filtering management requests search results
      properties:
        query:
          description: Free text query
          type:
          - string
          - 'null'
        origin:
          description: management request origin
          allOf:
          - $ref: '#/components/schemas/ManagementRequestOrigin'
        types:
          description: management request type
          items:
            $ref: '#/components/schemas/ManagementRequestType'
        status:
          description: request status
          allOf:
          - $ref: '#/components/schemas/ManagementRequestStatus'
        server_id:
          description: security server id
          type:
          - string
          - 'null'
      type: object
    EncodedId:
      type: object
      description: Encoded identifier
      properties:
        encoded_id:
          readOnly: true
          type: string
          description: Encoded ID of Security Server, Member or Subsystem Id
    ManagementRequestStatus:
      type: string
      readOnly: true
      description: request status
      enum:
      - WAITING
      - APPROVED
      - DECLINED
      - REVOKED
      - SUBMITTED FOR APPROVAL
    PagingSortingParameters:
      description: parameters for sorting and paging search results
      properties:
        sort:
          description: Indicates item property that is to be used as sorting key.
          example: title
          minLength: 2
          pattern: '[a-zA-Z_.]+'
          maxLength: 25
          type: string
        desc:
          description: 'Used sorting direction. Value ''true''  indicates descending and ''false'' or omitted parameter indicates ascending direction.

            '
          default: false
          type: boolean
        limit:
          description: 'Indicates the maximum number of items for the returned page.   If parameter is omitted, then the default amount of 25   is returned.

            '
          default: 25
          type: integer
          format: int32
        offset:
          description: 'Offset in pages from the beginning of the query result after filtering and sorting parameters are taken into account.  If the parameter omitted or the value 0 (zero) is given, the first page is returned.

            '
          default: 0
          type: integer
          format: int32
      type: object
    ManagementRequestType:
      type: string
      enum:
      - AUTH_CERT_REGISTRATION_REQUEST
      - CLIENT_REGISTRATION_REQUEST
      - OWNER_CHANGE_REQUEST
      - CLIENT_DELETION_REQUEST
      - CLIENT_DISABLE_REQUEST
      - CLIENT_ENABLE_REQUEST
      - CLIENT_RENAME_REQUEST
      - AUTH_CERT_DELETION_REQUEST
      - ADDRESS_CHANGE_REQUEST
      - SYSTEM_DID_REGISTRATION_REQUEST
      - MEMBER_DID_REGISTRATION_REQUEST
      - MAINTENANCE_MODE_ENABLE_REQUEST
      - MAINTENANCE_MODE_DISABLE_REQUEST
    ManagementRequestListView:
      type: object
      description: Management Request view
      properties:
        id:
          type: integer
          description: request id
          readOnly: true
        type:
          $ref: '#/components/schemas/ManagementRequestType'
        origin:
          $ref: '#/components/schemas/ManagementRequestOrigin'
        security_server_owner:
          type: string
          readOnly: true
        security_server_id:
          $ref: '#/components/schemas/SecurityServerId'
        address:
          type: string
        status:
          $ref: '#/components/schemas/ManagementRequestStatus'
        client_id:
          $ref: '#/components/schemas/ClientId'
        client_owner_name:
          type: string
          readOnly: true
        client_subsystem_name:
          type: string
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - type
      - origin
      - security_server_id
    KeyUsage:
      description: certificate key usage
      enum:
      - DIGITAL_SIGNATURE
      - NON_REPUDIATION
      - KEY_ENCIPHERMENT
      - DATA_ENCIPHERMENT
      - KEY_AGREEMENT
      - KEY_CERT_SIGN
      - CRL_SIGN
      - ENCIPHER_ONLY
      - DECIPHER_ONLY
      example: NON_REPUDIATION
      type: string
    XRoadId:
      type: object
      description: X-Road identifier
      discriminator:
        propertyName: type
        mapping:
          MEMBER: '#/components/schemas/ClientId'
          SERVER: '#/components/schemas/SecurityServerId'
          SUBSYSTEM: '#/components/schemas/ClientId'
      properties:
        instance_id:
          description: Xroad instance id. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: FI
          format: text
          maxLength: 255
          minLength: 1
          type: string
          readOnly: true
        type:
          type: string
          enum:
          - MEMBER
          - SUBSYSTEM
          - SERVER
          - GLOBALGROUP
          - SERVICE
          - LOCALGROUP
      required:
      - instance_id
      - type
    ModificationTimestamps:
      description: created_at and updated_at timestamps
      properties:
        created_at:
          description: object creation time
          example: '2022-01-20T00:00:00.001Z'
          format: date-time
          readOnly: true
          type: string
        updated_at:
          description: last time updated
          example: '2022-01-22T07:30:00.001Z'
          format: date-time
          readOnly: true
          type: string
      type: object
    ClientId:
      type: object
      description: Client identifier
      allOf:
      - $ref: '#/components/schemas/XRoadId'
      - $ref: '#/components/schemas/MemberId'
      - $ref: '#/components/schemas/EncodedId'
      properties:
        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
    ManagementRequest:
      type: object
      description: Management request
      allOf:
      - $ref: '#/components/schemas/ModificationTimestamps'
      discriminator:
        propertyName: type
        mapping:
          AUTH_CERT_REGISTRATION_REQUEST: '#/components/schemas/AuthenticationCertificateRegistrationRequest'
          AUTH_CERT_DELETION_REQUEST: '#/components/schemas/AuthenticationCertificateDeletionRequest'
          CLIENT_REGISTRATION_REQUEST: '#/components/schemas/ClientRegistrationRequest'
          CLIENT_DELETION_REQUEST: '#/components/schemas/ClientDeletionRequest'
          CLIENT_DISABLE_REQUEST: '#/components/schemas/ClientDisableRequest'
          CLIENT_ENABLE_REQUEST: '#/components/schemas/ClientEnableRequest'
          CLIENT_RENAME_REQUEST: '#/components/schemas/ClientRenameRequest'
          OWNER_CHANGE_REQUEST: '#/components/schemas/OwnerChangeRequest'
          ADDRESS_CHANGE_REQUEST: '#/components/schemas/AddressChangeRequest'
          SYSTEM_DID_REGISTRATION_REQUEST: '#/components/schemas/SystemDidRegistrationRequest'
          MEMBER_DID_REGISTRATION_REQUEST: '#/components/schemas/MemberDidRegistrationRequest'
          MAINTENANCE_MODE_ENABLE_REQUEST: '#/components/schemas/MaintenanceModeEnableRequest'
          MAINTENANCE_MODE_DISABLE_REQUEST: '#/components/schemas/MaintenanceModeDisableRequest'
      properties:
        id:
          type: integer
          description: request id
          readOnly: true
        type:
          $ref: '#/components/schemas/ManagementRequestType'
        origin:
          $ref: '#/components/schemas/ManagementRequestOrigin'
        security_server_owner:
          type: string
          readOnly: true
        security_server_id:
          type: string
          description: Encoded Security Server ID
        status:
          $ref: '#/components/schemas/ManagementRequestStatus'
        created_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - type
      - origin
      - security_server_id
    ManagementRequestOrigin:
      type: string
      description: request source
      enum:
      - CENTER
      - SECURITY_SERVER
    SecurityServerId:
      allOf:
      - $ref: '#/components/schemas/XRoadId'
      - $ref: '#/components/schemas/MemberId'
      - $ref: '#/components/schemas/EncodedId'
      type: object
      properties:
        server_code:
          description: security server code
          example: server123
          format: text
          maxLength: 255
          minLength: 1
          type: string
      required:
      - server_code
    PagingMetadata:
      description: metadata about paged results
      properties:
        total_items:
          description: Total number of items in the query results
          type: integer
          format: int32
        items:
          description: Number of items on the current page of query results
          type: integer
          format: int32
        limit:
          description: 'Indicates the maximum number of items for the returned page.

            '
          default: 25
          type: integer
          format: int32
        offset:
          description: 'Offset in pages from the beginning of the query result after filtering and sorting parameters are taken into account.

            '
          default: 0
          type: integer
          format: int32
      required:
      - total_items
      - items
      - limit
      - offset
      type: object
    CertificateDetails:
      description: certificate details for any kind of certificate (TLS, auth, sign)
      properties:
        hash:
          description: certificate SHA-256 hash
          example: 1234567890ABCDEF
          format: text
          maxLength: 64
          minLength: 1
          type: string
        issuer_common_name:
          description: certificate issuer common name
          example: domain.com
          format: text
          maxLength: 255
          minLength: 1
          type: string
        issuer_distinguished_name:
          description: certificate issuer distinguished name
          example: issuer123
          format: text
          maxLength: 255
          minLength: 1
          type: string
        key_usages:
          description: certificate key usage array
          items:
            $ref: '#/components/schemas/KeyUsage'
          type: array
          uniqueItems: false
        not_after:
          description: certificate validity not after
          example: '2022-01-17T00:00:00.001Z'
          format: date-time
          maxLength: 24
          minLength: 24
          type: string
        not_before:
          description: certificate validity not before
          example: '2022-01-17T00:00:00.001Z'
          format: date-time
          maxLength: 24
          minLength: 24
          type: string
        public_key_algorithm:
          description: certificate public key algorithm
          example: sha256WithRSAEncryption
          format: sha-256
          maxLength: 255
          minLength: 1
          type: string
        rsa_public_key_exponent:
          description: RSA public key exponent (if RSA key) as an integer
          example: 65537
          format: int32
          type: integer
        rsa_public_key_modulus:
          description: hex encoded RSA public key modulus (if RSA key)
          example: c44421d601...
          format: hex
          maxLength: 1000
          minLength: 1
          type: string
        ec_public_parameters:
          description: EC public key named 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
        serial:
          description: serial number
          example: '123456789'
          format: text
          maxLength: 255
          minLength: 1
          type: string
        signature:
          description: hex encoded certificate signature
          example: 30af2fdc1780...
          format: text
          maxLength: 255
          minLength: 1
          type: string
        signature_algorithm:
          description: certificate signature algorithm
          example: sha256WithRSAEncryption
          format: sha-256
          maxLength: 255
          minLength: 1
          type: string
        subject_alternative_names:
          description: certificate subject alternative names
          example: DNS:*.example.org
          format: text
          maxLength: 1000
          minLength: 1
          type: string
        subject_common_name:
          description: certificate subject common name
          example: domain.com
          format: text
          maxLength: 255
          minLength: 1
          type: string
        subject_distinguished_name:
          description: certificate subject distinguished name
          example: subject123
          format: text
          maxLength: 255
          minLength: 1
          type: string
        version:
          description: version
          example: 3
          format: int32
          type: integer
      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
      type: object
    MemberId:
      type: object
      description: Member identifier
      properties:
        member_class:
          description: Member class. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: GOV
          format: text
          maxLength: 255
          minLength: 1
          type: string
        member_code:
          description: Member code. Cannot contain colons, semicolons, slashes, backslashes, percent signs or control characters
          example: 123
          format: text
          maxLength: 255
          minLength: 1
          type: string
      required:
      - member_class
      - member_code
    PagedManagementRequests:
      description: an array of ManagementRequests with paging metadata
      properties:
        items:
          description: Management Requests
          items:
            $ref: '#/components/schemas/ManagementRequestListView'
          type: array
        paging_metadata:
          $ref: '#/components/schemas/PagingMetadata'
      required:
      - items
      - paging_metadata
      type: object
  parameters:
    ManagementRequestIdParam:
      in: path
      name: management_request_id
      description: Management request id
      required: true
      schema:
        minimum: 1
        format: int32
        type: integer
  securitySchemes:
    ApiKeyAuth:
      description: X-Road-ApiKey token=<api key>
      in: header
      name: Authorization
      type: apiKey
x-refined-from:
- central-server-admin-openapi.yaml
- x-road-global-central-server-admin-openapi.yml