{
  "swagger" : "2.0",
  "info" : {
    "description" : "An API for device admission handling. Intended for use by the web GUI.\n",
    "version" : "1",
    "title" : "Device admission"
  },
  "host" : "docker.mender.io",
  "basePath" : "/api/management/v1/admission",
  "schemes" : [ "https" ],
  "paths" : {
    "/devices" : {
      "get" : {
        "summary" : "List known device data sets",
        "description" : "Returns a paged collection of device authentication data sets registered\nfor admission, and optionally filters by device admission status.\n",
        "parameters" : [ {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        }, {
          "name" : "status",
          "in" : "query",
          "description" : "Admission status filter. If not specified, all device data sets are listed.\n",
          "required" : false,
          "type" : "string",
          "enum" : [ "pending", "accepted", "rejected", "preauthorized" ]
        }, {
          "name" : "page",
          "in" : "query",
          "description" : "Starting page.",
          "required" : false,
          "type" : "number",
          "default" : 1.0,
          "format" : "integer"
        }, {
          "name" : "per_page",
          "in" : "query",
          "description" : "Number of results per page.",
          "required" : false,
          "type" : "number",
          "default" : 10.0,
          "format" : "integer"
        }, {
          "name" : "device_id",
          "in" : "query",
          "description" : "List auth sets owned by given device",
          "required" : false,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "Successful response.",
            "schema" : {
              "type" : "array",
              "example" : {
                "application/json" : [ {
                  "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
                  "device_id" : "58be8208dd77460001fe0d78",
                  "device_identity" : "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}",
                  "key" : "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n",
                  "status" : "pending",
                  "attributes" : {
                    "mac" : "00:01:02:03:04:05",
                    "sku" : "My Device 1",
                    "sn" : "SN1234567890"
                  },
                  "request_time" : "2016-10-03T16:58:51.639Z"
                } ]
              },
              "title" : "ListOfDevices",
              "items" : {
                "$ref" : "#/definitions/Device"
              }
            },
            "headers" : {
              "Link" : {
                "type" : "string",
                "description" : "Standard header, used for page navigation.\n\nSupported relation types are 'first', 'next' and 'prev'.\n"
              }
            }
          },
          "400" : {
            "description" : "Invalid parameters. See error message for details.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      },
      "post" : {
        "summary" : "Submit a preauthorized device authentication data set",
        "description" : "Adds the device authentication data set to the database with a 'preauthorized'\nadmission status. The device identity data set must not yet exist in the DB (regardless of status).\n\nWhen the device requests authentication from deviceauth the next time, it will be issued\na token without further user intervention.\n",
        "parameters" : [ {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        }, {
          "in" : "body",
          "name" : "auth_set",
          "description" : "The authentication data set to be preauthorized",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/AuthSet"
          }
        } ],
        "responses" : {
          "201" : {
            "description" : "Device authentication data set submitted successfully.",
            "headers" : {
              "Location" : {
                "type" : "string",
                "description" : "Link to the created auth set."
              }
            }
          },
          "400" : {
            "description" : "The request body is malformed. See error for details.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "409" : {
            "description" : "Authentication data set (identity data) already exists.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      }
    },
    "/devices/{id}" : {
      "get" : {
        "summary" : "Get the details of a selected device authentication data set",
        "description" : "Returns the details of a particular device authentication data set.",
        "parameters" : [ {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        }, {
          "name" : "id",
          "in" : "path",
          "description" : "Device authentication data set identifier.",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "Successful response - a device authentication data set is returned.",
            "schema" : {
              "$ref" : "#/definitions/Device"
            },
            "examples" : {
              "application/json" : {
                "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
                "device_id" : "58be8208dd77460001fe0d78",
                "device_identity" : "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}",
                "key" : "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n",
                "status" : "pending",
                "attributes" : {
                  "mac" : "00:01:02:03:04:05",
                  "sku" : "My Device 1",
                  "sn" : "SN1234567890"
                },
                "request_time" : "2016-10-03T16:58:51.639Z"
              }
            }
          },
          "404" : {
            "description" : "The device authentication data set was not found.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      },
      "put" : {
        "summary" : "Submit a device authentication data set for admission",
        "description" : "Deprecated endpoint, will be removed in Mender 1.6\nAdds the device authentication data set to the database with a 'pending'\nadmission status. If the device already exists, it changes the device's\nstatus to 'pending' and updates identity data. The user will be able to\ninspect the device, and either accept, or reject it.\n",
        "parameters" : [ {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        }, {
          "name" : "id",
          "in" : "path",
          "description" : "Device authentication data set identifier.",
          "required" : true,
          "type" : "string"
        }, {
          "in" : "body",
          "name" : "device",
          "description" : "A device for admission.",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/NewDevice"
          }
        } ],
        "responses" : {
          "204" : {
            "description" : "Device authentication data set submitted successfully."
          },
          "400" : {
            "description" : "The request body is malformed. See error for details.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      },
      "delete" : {
        "summary" : "Remove device authentication data set",
        "description" : "Removes all device authentication data set data.",
        "parameters" : [ {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        }, {
          "name" : "id",
          "in" : "path",
          "description" : "Device authentication data set identifier",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "204" : {
            "description" : "The device authentication data set was removed."
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      }
    },
    "/devices/{id}/status" : {
      "get" : {
        "summary" : "Check the admission status of a selected device authentication data set",
        "description" : "Returns the admission status of a particular device authentication data set.",
        "parameters" : [ {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        }, {
          "name" : "id",
          "in" : "path",
          "description" : "Device authentication data set identifier.",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "Successful response - the device's admission status is returned.\n",
            "schema" : {
              "$ref" : "#/definitions/Status"
            },
            "examples" : {
              "application/json" : {
                "status" : "accepted"
              }
            }
          },
          "404" : {
            "description" : "The device authentication data set was not found.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      },
      "put" : {
        "summary" : "Update the admission status of a selected device",
        "description" : "Changes the given device's admission status.\nValid state transitions:\n- 'pending' -> 'accepted'\n- 'pending' -> 'rejected'\n- 'rejected' -> 'accepted'\n- 'accepted' -> 'rejected'\n",
        "parameters" : [ {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        }, {
          "name" : "id",
          "in" : "path",
          "description" : "Device authentication data set identifier.",
          "required" : true,
          "type" : "string"
        }, {
          "in" : "body",
          "name" : "status",
          "description" : "New status",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/Status"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "The status of the device authentication data set was successfully updated.",
            "schema" : {
              "$ref" : "#/definitions/Status"
            },
            "examples" : {
              "application/json" : {
                "status" : "accepted"
              }
            }
          },
          "400" : {
            "description" : "The request body is malformed or the state transition is invalid. See error for details.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "404" : {
            "description" : "The device authentication data set was not found.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      }
    }
  },
  "definitions" : {
    "Error" : {
      "type" : "object",
      "properties" : {
        "error" : {
          "type" : "string",
          "description" : "Description of the error."
        },
        "request_id" : {
          "type" : "string",
          "description" : "Request ID (same as in X-MEN-RequestID header)."
        }
      },
      "description" : "Error descriptor.",
      "example" : {
        "application/json" : {
          "error" : "failed to decode device group data: JSON payload is empty",
          "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
        }
      }
    },
    "NewDevice" : {
      "type" : "object",
      "required" : [ "device_id", "device_identity", "key" ],
      "properties" : {
        "device_identity" : {
          "type" : "string",
          "description" : "The identity data of the device."
        },
        "key" : {
          "type" : "string",
          "description" : "Device public key"
        },
        "device_id" : {
          "type" : "string",
          "description" : "System-assigned device ID."
        }
      },
      "description" : "New device authentication data set for admission process.",
      "example" : {
        "application/json" : {
          "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
          "device_id" : "58be8208dd77460001fe0d78",
          "device_identity" : "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}",
          "key" : "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
        }
      }
    },
    "AuthSet" : {
      "type" : "object",
      "required" : [ "device_identity", "key" ],
      "properties" : {
        "device_identity" : {
          "type" : "string",
          "description" : "The identity data of the device."
        },
        "key" : {
          "type" : "string",
          "description" : "Device public key."
        }
      },
      "description" : "New device authentication data set.",
      "example" : {
        "application/json" : {
          "device_identity" : "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}",
          "key" : "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n"
        }
      }
    },
    "Device" : {
      "type" : "object",
      "required" : [ "attributes", "device_id", "device_identity", "id", "key", "request_time", "status" ],
      "properties" : {
        "id" : {
          "type" : "string",
          "description" : "Authentication data set identifier."
        },
        "device_id" : {
          "type" : "string",
          "description" : "System assigned device identifier."
        },
        "device_identity" : {
          "type" : "string",
          "description" : "Identity data"
        },
        "key" : {
          "type" : "string",
          "description" : "Device public key"
        },
        "status" : {
          "type" : "string",
          "description" : "Status of the admission process for device authentication data set",
          "enum" : [ "pending", "accepted", "rejected", "preauthorized" ]
        },
        "attributes" : {
          "$ref" : "#/definitions/Attributes"
        },
        "request_time" : {
          "type" : "string",
          "format" : "datetime",
          "description" : "Server-side timestamp of the request reception."
        }
      },
      "description" : "Device authentication data set descriptor.",
      "example" : {
        "application/json" : {
          "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
          "device_id" : "58be8208dd77460001fe0d78",
          "device_identity" : "{\"mac\":\"00:01:02:03:04:05\", \"sku\":\"My Device 1\", \"sn\":\"SN1234567890\"}",
          "key" : "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzogVU7RGDilbsoUt/DdH\nVJvcepl0A5+xzGQ50cq1VE/Dyyy8Zp0jzRXCnnu9nu395mAFSZGotZVr+sWEpO3c\nyC3VmXdBZmXmQdZqbdD/GuixJOYfqta2ytbIUPRXFN7/I7sgzxnXWBYXYmObYvdP\nokP0mQanY+WKxp7Q16pt1RoqoAd0kmV39g13rFl35muSHbSBoAW3GBF3gO+mF5Ty\n1ddp/XcgLOsmvNNjY+2HOD5F/RX0fs07mWnbD7x+xz7KEKjF+H7ZpkqCwmwCXaf0\niyYyh1852rti3Afw4mDxuVSD7sd9ggvYMc0QHIpQNkD4YWOhNiE1AB0zH57VbUYG\nUwIDAQAB\n-----END PUBLIC KEY-----\n",
          "status" : "pending",
          "attributes" : {
            "mac" : "00:01:02:03:04:05",
            "sku" : "My Device 1",
            "sn" : "SN1234567890"
          },
          "request_time" : "2016-10-03T16:58:51.639Z"
        }
      }
    },
    "Status" : {
      "type" : "object",
      "required" : [ "status" ],
      "properties" : {
        "status" : {
          "type" : "string",
          "enum" : [ "pending", "accepted", "rejected" ]
        }
      },
      "description" : "Admission status of device authentication data set.",
      "example" : {
        "application/json" : {
          "status" : "accepted"
        }
      }
    },
    "Attributes" : {
      "type" : "object",
      "properties" : {
        "mac" : {
          "type" : "string",
          "description" : "MAC address."
        },
        "sku" : {
          "type" : "string",
          "description" : "Stock keeping unit."
        },
        "sn" : {
          "type" : "string",
          "description" : "Serial number."
        }
      },
      "description" : "Human readable attributes of the device, in the form of a JSON structure.\nThe attributes are completely vendor-specific, the provided ones are just an example.\n",
      "example" : {
        "application/json" : {
          "mac" : "00:01:02:03:04:05",
          "sku" : "My Device 1",
          "sn" : "SN1234567890"
        }
      }
    }
  }
}