{
  "openapi" : "3.0.0",
  "info" : {
    "contact" : {
      "email" : "support@boschrexroth.com",
      "name" : "Bosch Rexroth AG",
      "url" : "https://www.boschrexroth.com"
    },
    "description" : "This is the API for initiating the Device Registration process on an ctrlX OS Device. It is necessary to \nobtain a valid ctrlX Device Certificate uniquely identifying the device by the ctrlX Device ID. \n\nTherefore, the user initiate the device to register itself (see \"POST /tasks\"). The process is as follows:\n* The device needs to be granted access to the ctrlX Device Portal on behalf of your ctrlX Device Portal account. \n* Then, the device can request the ctrlX Device Certificate on its own.\n\nThe registration process can only be started if the device is not preprovisioned with a ctrlX Device Certificate. \nA physical TPM is mandatory.\n",
    "title" : "ctrlX OS - Device Registration API",
    "version" : "1.3.0"
  },
  "servers" : [ {
    "url" : "/device-registration/api/v1"
  }, {
    "url" : "https://{host}/device-registration/api/v1",
    "variables" : {
      "host" : {
        "default" : "localhost:443",
        "description" : "Hostname or ip address of the ctrlX OS system"
      }
    }
  } ],
  "security" : [ {
    "BearerAuth" : [ ]
  } ],
  "tags" : [ {
    "description" : "Registration process information",
    "name" : "Information"
  }, {
    "description" : "Registration process tasks",
    "name" : "Registration"
  } ],
  "paths" : {
    "/information" : {
      "get" : {
        "description" : "Get the current state of the registration process",
        "operationId" : "getRegistrationInformation",
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DeviceRegistrationInformation"
                }
              }
            },
            "description" : "Returns information about the registration process"
          },
          "400" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Loading configuration failed",
                  "status" : 400,
                  "instance" : "/solutions/configuration",
                  "mainDiagnosisCode" : "080F0400",
                  "severity" : "Warning",
                  "links" : [ "https://docs.automation.boschrexroth.com/cdphelp?tkeyword=080F0400" ],
                  "cause" : [ {
                    "type" : "about:blank",
                    "title" : "Error in system configuration",
                    "detail" : "Creation and deletion of motion objects is only allowed in CONFIGURATION state",
                    "status" : 400,
                    "instance" : "/automation/api/v2/nodes/motion/cmd/opstate",
                    "mainDiagnosisCode" : "090F2020",
                    "detailedDiagnosisCode" : "0C560203",
                    "severity" : "Warning",
                    "links" : [ "https://docs.automation.boschrexroth.com/cdphelp?tkeyword=0C560203" ]
                  }, {
                    "type" : "about:blank",
                    "title" : "Error in PLC configuration",
                    "detail" : "Loading the configuration in the “RUN” state is not permitted",
                    "status" : 400,
                    "instance" : "/automation/api/v2/nodes/plc/cmd/run",
                    "mainDiagnosisCode" : "0A0F0020",
                    "detailedDiagnosisCode" : "0C280100",
                    "severity" : "Warning",
                    "links" : [ "https://docs.automation.boschrexroth.com/cdphelp?tkeyword=0C280100" ]
                  } ]
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "The request is incomplete or malformed"
          },
          "401" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Unauthorized (401)",
                  "status" : 401,
                  "instance" : "scheduler/admin",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0203",
                  "severity" : "Error"
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Not authorized to access this resource"
          },
          "403" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Forbidden (403)",
                  "status" : 403,
                  "instance" : "scheduler/admin/state",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0204",
                  "severity" : "Error",
                  "moreInfo" : {
                    "requiredPermissions" : "rexroth-automation.datalayer.rw, rexroth-device.all.rwx"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Access forbidden for this resource"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http server error",
                  "detail" : "Internal server error (500)",
                  "status" : 500,
                  "instance" : "scheduler/admin",
                  "mainDiagnosisCode" : "080F0200",
                  "detailedDiagnosisCode" : "0C7A0200",
                  "severity" : "Error",
                  "moreInfo" : {
                    "trace" : "ExampleClass.cpp#452 Null pointer exception"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Something unexpected happened on the server"
          }
        },
        "summary" : "Get the information of the registration process",
        "tags" : [ "Information" ]
      }
    },
    "/tasks" : {
      "get" : {
        "description" : "Receive the list of created tasks",
        "operationId" : "getTasks",
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Tasks"
                }
              }
            },
            "description" : "List of Tasks"
          },
          "401" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Unauthorized (401)",
                  "status" : 401,
                  "instance" : "scheduler/admin",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0203",
                  "severity" : "Error"
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Not authorized to access this resource"
          },
          "403" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Forbidden (403)",
                  "status" : 403,
                  "instance" : "scheduler/admin/state",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0204",
                  "severity" : "Error",
                  "moreInfo" : {
                    "requiredPermissions" : "rexroth-automation.datalayer.rw, rexroth-device.all.rwx"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Access forbidden for this resource"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http server error",
                  "detail" : "Internal server error (500)",
                  "status" : 500,
                  "instance" : "scheduler/admin",
                  "mainDiagnosisCode" : "080F0200",
                  "detailedDiagnosisCode" : "0C7A0200",
                  "severity" : "Error",
                  "moreInfo" : {
                    "trace" : "ExampleClass.cpp#452 Null pointer exception"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Something unexpected happened on the server"
          }
        },
        "summary" : "Receive a list of tasks",
        "tags" : [ "Registration" ]
      },
      "post" : {
        "description" : "The task follows the registration process described in [DeviceRegistrationInformation]('#/components/schemas/DeviceRegistrationInformation').",
        "operationId" : "createTask",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "examples" : {
                "registerDeviceTaskRequest" : {
                  "$ref" : "#/components/examples/registerDeviceRequest"
                }
              },
              "schema" : {
                "$ref" : "#/components/schemas/OneOfTasks"
              }
            }
          }
        },
        "responses" : {
          "201" : {
            "content" : {
              "application/json" : {
                "examples" : {
                  "registerDeviceTaskResponse" : {
                    "$ref" : "#/components/examples/registerDeviceResponse"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/OneOfTasks"
                }
              }
            },
            "description" : "Task created",
            "headers" : {
              "Location" : {
                "explode" : false,
                "schema" : {
                  "description" : "Location of the created task",
                  "example" : "/device-registration/api/v1/tasks/123",
                  "type" : "string"
                },
                "style" : "simple"
              }
            }
          },
          "401" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Forbidden (403)",
                  "status" : 403,
                  "instance" : "scheduler/admin/state",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0204",
                  "severity" : "Error",
                  "moreInfo" : {
                    "requiredPermissions" : "rexroth-automation.datalayer.rw, rexroth-device.all.rwx"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Access forbidden for this resource"
          },
          "403" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Forbidden (403)",
                  "status" : 403,
                  "instance" : "scheduler/admin/state",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0204",
                  "severity" : "Error",
                  "moreInfo" : {
                    "requiredPermissions" : "rexroth-automation.datalayer.rw, rexroth-device.all.rwx"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Access forbidden for this resource"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Forbidden (403)",
                  "status" : 403,
                  "instance" : "scheduler/admin/state",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0204",
                  "severity" : "Error",
                  "moreInfo" : {
                    "requiredPermissions" : "rexroth-automation.datalayer.rw, rexroth-device.all.rwx"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Access forbidden for this resource"
          }
        },
        "summary" : "Create a new registration task",
        "tags" : [ "Registration" ]
      }
    },
    "/tasks/{taskId}" : {
      "get" : {
        "description" : "Receive information about a task",
        "operationId" : "getTask",
        "parameters" : [ {
          "description" : "The unique task Id",
          "explode" : false,
          "in" : "path",
          "name" : "taskId",
          "required" : true,
          "schema" : {
            "type" : "string"
          },
          "style" : "simple"
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "examples" : {
                  "registerDeviceTaskResponse" : {
                    "$ref" : "#/components/examples/registerDeviceResponse"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/OneOfTasks"
                }
              }
            },
            "description" : "Done - Task information"
          },
          "401" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Unauthorized (401)",
                  "status" : 401,
                  "instance" : "scheduler/admin",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0203",
                  "severity" : "Error"
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Not authorized to access this resource"
          },
          "403" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Forbidden (403)",
                  "status" : 403,
                  "instance" : "scheduler/admin/state",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0204",
                  "severity" : "Error",
                  "moreInfo" : {
                    "requiredPermissions" : "rexroth-automation.datalayer.rw, rexroth-device.all.rwx"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Access forbidden for this resource"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http client error",
                  "detail" : "Not found (404)",
                  "status" : 404,
                  "instance" : "scheduler/not-available",
                  "mainDiagnosisCode" : "080E0200",
                  "detailedDiagnosisCode" : "0C7A0205",
                  "severity" : "Error"
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "The resource was not found"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "example" : {
                  "type" : "about:blank",
                  "title" : "Http server error",
                  "detail" : "Internal server error (500)",
                  "status" : 500,
                  "instance" : "scheduler/admin",
                  "mainDiagnosisCode" : "080F0200",
                  "detailedDiagnosisCode" : "0C7A0200",
                  "severity" : "Error",
                  "moreInfo" : {
                    "trace" : "ExampleClass.cpp#452 Null pointer exception"
                  }
                },
                "schema" : {
                  "$ref" : "#/components/schemas/Problem"
                }
              }
            },
            "description" : "Something unexpected happened on the server"
          }
        },
        "summary" : "Receive information about a task",
        "tags" : [ "Registration" ]
      }
    }
  },
  "components" : {
    "examples" : {
      "registerDeviceRequest" : {
        "value" : {
          "action" : "register"
        }
      },
      "registerDeviceResponse" : {
        "value" : {
          "id" : "123",
          "state" : "done",
          "progress" : 100,
          "eta" : "2019-01-01T12:00:27.87+00:20",
          "action" : "register"
        }
      }
    },
    "schemas" : {
      "DeviceRegistrationInformation" : {
        "description" : "The information of the device registration",
        "example" : {
          "verificationUriComplete" : "https://sandbox.auth.boschrexroth.com/auth/realms/dc2/device?user_code=ABCD-EFGH",
          "userCode" : "ABCD-EFGH",
          "verificationUri" : "https://sandbox.auth.boschrexroth.com/auth/realms/dc2/device",
          "status" : "unregistered"
        },
        "properties" : {
          "status" : {
            "description" : "The status of the registration process on the device.\n* unregistered: The device is not registered yet. The user can start the registration process.\n* waitingForGrant: The device is waiting for the user to grant access to the ctrlX Device Portal. \n    See further details in userCode, verificationUri and verificationUriComplete.\n* running: The device is currently running the registration process.\n* registered: The device has been successfully registered.\n* notApplicable: The device cannot be registered due to technical constraints.\n* failed: The device registration has failed.\n",
            "enum" : [ "unregistered", "waitingForGrant", "running", "registered", "notApplicable", "failed" ],
            "type" : "string"
          },
          "userCode" : {
            "description" : "The code the user needs to enter into ctrlX Device Portal to grant access to the device  for further registration steps. The device polls the ctrlX Device Portal automatically  if access has been granted. This date is shown only in status \"waitingForGrant\".\n",
            "example" : "ABCD-EFGH",
            "type" : "string"
          },
          "verificationUri" : {
            "description" : "The URI to verify the device in ctrlX Device Portal, where the user needs to enter the user code. This date is shown only in status \"waitingForGrant\".\n",
            "example" : "https://sandbox.auth.boschrexroth.com/auth/realms/dc2/device",
            "type" : "string"
          },
          "verificationUriComplete" : {
            "description" : "The URI to verify the device directly in ctrlX Device Portal. This date is shown only in status \"waitingForGrant\".\n",
            "example" : "https://sandbox.auth.boschrexroth.com/auth/realms/dc2/device?user_code=ABCD-EFGH",
            "type" : "string"
          }
        },
        "required" : [ "status" ],
        "type" : "object"
      },
      "OneOfTasks" : {
        "discriminator" : {
          "propertyName" : "action"
        },
        "oneOf" : [ {
          "$ref" : "#/components/schemas/TaskRegisterDevice"
        } ]
      },
      "Tasks" : {
        "items" : {
          "$ref" : "#/components/schemas/OneOfTasks"
        },
        "type" : "array"
      },
      "Problem" : {
        "description" : "This document defines a \"problem detail\" as a way  to carry machine-readable details of errors in a  HTTP response to avoid the need to define new error  response formats for HTTP APIs.\n",
        "properties" : {
          "type" : {
            "default" : "about:blank",
            "description" : "A URI reference [RFC3986] that identifies the problem type. \nThis specification encourages that, when dereferenced, \nit provide human-readable documentation for the problem type \n(e.g., using HTML [W3C.REC-html5-20141028]). When this member \nis not present, its value is assumed to be \"about:blank\".\n",
            "example" : "https://example.com/probs/out-of-credit",
            "format" : "uri",
            "type" : "string"
          },
          "title" : {
            "description" : "A short, human-readable summary of the problem type. \nIt SHOULD NOT change from occurrence to occurrence of the problem, \nexcept for purposes of localization (e.g., using proactive content \nnegotiation; see [RFC7231], Section 3.4).\nIf the response is a diagnostics message, it contains \nthe text associated with the mainDiagnosisCode.\n",
            "example" : "You do not have enough credit.",
            "type" : "string"
          },
          "status" : {
            "description" : "The HTTP status code ([RFC7231], Section 6) generated by the \norigin server for this occurrence of the problem.\n",
            "example" : 403,
            "format" : "int32",
            "type" : "integer"
          },
          "detail" : {
            "description" : "A human-readable explanation specific to this occurrence of the problem.\nIf the response is a diagnostics message, it contains the text associated with\nthe detailedDiagnosisCode.\n",
            "example" : "Your current balance is 30, but that costs 50.",
            "type" : "string"
          },
          "instance" : {
            "description" : "A URI reference that identifies the specific occurrence of the problem.\nIt may or may not yield further information if dereferenced.\n",
            "example" : "/account/12345/msgs/abc",
            "type" : "string"
          },
          "code" : {
            "deprecated" : true,
            "description" : "An error code issued by the system that caused the original problem.\nThis code can be used to track down the root cause of the error.\n",
            "example" : "F360001",
            "type" : "string"
          },
          "mainDiagnosisCode" : {
            "description" : "The main diagnosis code is issued by the system that caused the problem.\nThis code can be used to track down the root cause and source of the error.\nIt can be used to search in the documentation for a solution.\nIt SHOULD NOT change from occurrence to occurrence of the same problem.\n",
            "example" : "080F0100",
            "type" : "string"
          },
          "detailedDiagnosisCode" : {
            "description" : "The detailed diagnosis code issued by the system that caused the problem.\nThis code can be used to track down the detailed cause and source of the error.\nIt can be used to search in the documentation for a solution.\nThe detailed diagnosis code gives additional information about the cause of the error.\nIt SHOULD NOT change from occurrence to occurrence of the same problem.\n",
            "example" : "00666001",
            "type" : "string"
          },
          "dynamicDescription" : {
            "description" : "A dynamic description gives detailed information about the occurrence of a problem.\nIt can change between different occurrences of the same error.\n",
            "example" : "value = -4.5",
            "type" : "string"
          },
          "severity" : {
            "description" : " Severity of a problem as defined RFC5424 of the Syslog standard, see https://tools.ietf.org/html/rfc5424",
            "enum" : [ "Emergency", "Alert", "Critical", "Error", "Warning", "Notice", "Informational", "Debug" ],
            "example" : "Error",
            "type" : "string"
          },
          "links" : {
            "description" : "Collection of links to fix the problem. E.g. links to online user manual,\nto an online community (using tags) or a developer chat (e.g. Slack).\n",
            "items" : {
              "example" : "https://stackoverflow.com/questions/tagged/boschrexroth+controlx+f360001",
              "format" : "uri",
              "type" : "string"
            },
            "type" : "array"
          },
          "moreInfo" : {
            "additionalProperties" : true,
            "description" : "The moreInfo field allows you to add additional information that might be necessary to debug or trace down the cause of an error.\nIt might also contain information what is needed to resolve the problem.\nThere are loosely specified fields for specific problems that can be used in these situations, e.g.:\n- On a 403 Forbidden error: The moreInfo can contain a field \"requiredPermissions\" with the required permissions seperated by comma\n- On a 402 Payment required: The moreInfo can contain a field \"requiredLicenses\" with the required licenses seperated by comma\n",
            "example" : {
              "trace" : "ExampleClass.cpp#452 Null pointer exception",
              "class" : "ExampleClass"
            },
            "type" : "object"
          },
          "cause" : {
            "description" : "Sometimes a problem might be caused by problems that occure in other components or are the root cause of a problem. In this\ncase the related problems can be added as a cause. Since it might be possible that multiple components have problems on a single\naction, cause is an array. E.g. Loading failed because several components where not able to load the configuration.\n",
            "items" : {
              "$ref" : "#/components/schemas/Problem"
            },
            "type" : "array"
          }
        },
        "required" : [ "title", "type" ],
        "type" : "object",
        "x-version" : "1.0.0"
      },
      "TaskRegisterDevice" : {
        "allOf" : [ {
          "$ref" : "#/components/schemas/Task"
        }, {
          "$ref" : "#/components/schemas/TaskRegisterDevice_allOf"
        } ],
        "description" : "Run process to register a device"
      },
      "Task" : {
        "discriminator" : {
          "propertyName" : "action"
        },
        "properties" : {
          "id" : {
            "description" : "A server generated ID used to identify the task. This ID is unique.",
            "example" : "123",
            "readOnly" : true,
            "type" : "string"
          },
          "state" : {
            "description" : "The state of the task.",
            "enum" : [ "pending", "failed", "done", "running" ],
            "example" : "running",
            "readOnly" : true,
            "type" : "string"
          },
          "action" : {
            "description" : "The action name executed by this task. This has to be inherited and overwritten by the application.",
            "type" : "string"
          },
          "progress" : {
            "description" : "Optional progress of the task in percentage.",
            "example" : 10,
            "maximum" : 100,
            "minimum" : 0,
            "readOnly" : true,
            "type" : "integer"
          },
          "eta" : {
            "description" : "Optional ETA in RFC 3339 format.",
            "example" : "2019-01-01T12:00:27.87+00:20",
            "format" : "dateTime",
            "readOnly" : true,
            "type" : "string"
          },
          "parameters" : {
            "additionalProperties" : true,
            "description" : "Optional map of additional parameters required by the request. Should be defined when inherited by an application.",
            "type" : "object"
          },
          "result" : {
            "additionalProperties" : true,
            "description" : "Optional map reflecting the result of the task. May be empty until task completition. Should be defined when inherited by an application.",
            "readOnly" : true,
            "type" : "object"
          }
        },
        "required" : [ "action", "id", "state" ],
        "type" : "object"
      },
      "TaskRegisterDevice_allOf_parameters" : {
        "description" : "The parameters required to register the device. This includes the account ID to which the device should be registered.\n",
        "properties" : {
          "accountId" : {
            "description" : "The account ID the device should be registered to",
            "example" : "1234567890",
            "type" : "string"
          }
        },
        "required" : [ "accountId" ]
      },
      "TaskRegisterDevice_allOf" : {
        "properties" : {
          "action" : {
            "enum" : [ "register" ],
            "type" : "string"
          },
          "parameters" : {
            "$ref" : "#/components/schemas/TaskRegisterDevice_allOf_parameters"
          },
          "result" : {
            "$ref" : "#/components/schemas/Problem"
          }
        },
        "required" : [ "action", "parameters" ]
      }
    },
    "securitySchemes" : {
      "BearerAuth" : {
        "scheme" : "bearer",
        "type" : "http"
      }
    }
  }
}