{
  "swagger" : "2.0",
  "info" : {
    "description" : "An API for user administration and user authentication handling. Intended for use by the web GUI.\nAll responses from the API will contain 'X-MEN-RequestID' header with server-side generated request ID.\n",
    "version" : "1",
    "title" : "User administration and authentication"
  },
  "host" : "docker.mender.io",
  "basePath" : "/api/management/v1/useradm",
  "schemes" : [ "https" ],
  "paths" : {
    "/auth/login" : {
      "post" : {
        "summary" : "Log in to Mender",
        "description" : "Accepts user credentials via standard Basic Auth, and returns a\nJWT token to be used for authentication in subsequent requests.\n",
        "parameters" : [ {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Standard Basic Auth header, based on user's credentials.\n",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "Authentication successful - a new JWT is issued and returned.\nThe JWT is signed with the API's private key ('RS256' signing algorithm),\nand contains the following standard claims:\n* 'iss' - issuer\n* 'exp' - expiry date\n* 'sub' - unique, autogenerated user ID\n* 'scp' - 'mender.*', allows access to all APIs/methods\n",
            "examples" : {
              "application/jwt" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9. eyJleHAiOjE0NzYxMTkxMzYsImlzcyI6Ik1lbmRlciIsIn N1YiI6Ijg1NGIzMTA5LTQ4NjItNGEyNS1hMWZiLWYxMTE2 MWNlN2E4NCIsInNjcCI6WyJtZW5kZXIuKiJdfQ. X7Ief4PhPLlR6mA2wh3G3K0Z2tud0rK1QJesxu52NfICSe ARmlujczs-_1YZxMwI0s-HgpXHbXIjaSVK80BjxjAM1rqp RGvgqSqG-dU5KmglDpAaTr4VaJci3VFPlVUVTRpI7bfqNM nKZtjmOUAGwjvroDUwX1RwayEmms-efGI"
            }
          },
          "400" : {
            "description" : "Bad request, see error message for details.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "401" : {
            "description" : "Unauthorized.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      }
    },
    "/users" : {
      "get" : {
        "summary" : "List users",
        "description" : "Returns a non-paged collection of users information.\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]"
        } ],
        "responses" : {
          "200" : {
            "description" : "Successful response.",
            "schema" : {
              "type" : "array",
              "title" : "ListOfUsers",
              "items" : {
                "$ref" : "#/definitions/User"
              }
            }
          },
          "401" : {
            "description" : "The user cannot be granted authentication.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      },
      "post" : {
        "summary" : "Create user",
        "parameters" : [ {
          "in" : "body",
          "name" : "user",
          "description" : "New user data.",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/UserNew"
          }
        }, {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        } ],
        "responses" : {
          "201" : {
            "description" : "The user was successfully created.",
            "headers" : {
              "Location" : {
                "type" : "string",
                "description" : "URI for the newly created 'User' resource."
              }
            }
          },
          "400" : {
            "description" : "The request body is malformed.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "401" : {
            "description" : "The user cannot be granted authentication.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "422" : {
            "description" : "The email address is duplicated or password is too short.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      }
    },
    "/users/{id}" : {
      "get" : {
        "summary" : "Get user information",
        "description" : "Returns user information.\n",
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "description" : "User id.",
          "required" : true,
          "type" : "string"
        }, {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        } ],
        "responses" : {
          "200" : {
            "description" : "Successful response - a user information is returned.",
            "schema" : {
              "$ref" : "#/definitions/User"
            }
          },
          "401" : {
            "description" : "The user cannot be granted authentication.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "404" : {
            "description" : "The user was not found.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      },
      "put" : {
        "summary" : "Update user information",
        "description" : "Update user email or change user password.\n",
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "description" : "User id.",
          "required" : true,
          "type" : "string"
        }, {
          "in" : "body",
          "name" : "user_update",
          "description" : "Updated user data.",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/UserUpdate"
          }
        }, {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        } ],
        "responses" : {
          "204" : {
            "description" : "User information updated."
          },
          "400" : {
            "description" : "The request body is malformed.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "401" : {
            "description" : "The user cannot be granted authentication.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "404" : {
            "description" : "The user does not exist.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "422" : {
            "description" : "The email address is duplicated or password is too short.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      },
      "delete" : {
        "summary" : "Remove user from the system",
        "description" : "Remove user information from the system.\n",
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "description" : "User id.",
          "required" : true,
          "type" : "string"
        }, {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        } ],
        "responses" : {
          "204" : {
            "description" : "User removed."
          },
          "401" : {
            "description" : "The user cannot be granted authentication.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      }
    },
    "/settings" : {
      "get" : {
        "summary" : "Get user settings",
        "description" : "Returns user settings.\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]"
        } ],
        "responses" : {
          "200" : {
            "description" : "Successful response - a user information is returned.",
            "schema" : {
              "$ref" : "#/definitions/Settings"
            }
          },
          "401" : {
            "description" : "The user cannot be granted authentication.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      },
      "post" : {
        "summary" : "Set user settings",
        "description" : "Create user settings or replace existing settings with provided object.\n",
        "parameters" : [ {
          "in" : "body",
          "name" : "settings",
          "description" : "New user settings.",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/Settings"
          }
        }, {
          "name" : "Authorization",
          "in" : "header",
          "description" : "Contains the JWT token issued by the User Administration and Authentication Service.",
          "required" : true,
          "type" : "string",
          "format" : "Bearer [token]"
        } ],
        "responses" : {
          "201" : {
            "description" : "User settings set."
          },
          "400" : {
            "description" : "The request body is malformed.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "401" : {
            "description" : "The user cannot be granted authentication.\n",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          },
          "500" : {
            "description" : "Internal server error.",
            "schema" : {
              "$ref" : "#/definitions/Error"
            }
          }
        }
      }
    }
  },
  "definitions" : {
    "UserNew" : {
      "type" : "object",
      "required" : [ "email", "password" ],
      "properties" : {
        "email" : {
          "type" : "string",
          "description" : "A unique email address. Invalid characters are non-ascii and '+'."
        },
        "password" : {
          "type" : "string",
          "description" : "Password."
        }
      },
      "description" : "New user descriptor.",
      "example" : {
        "application/json" : {
          "email" : "user@acme.com",
          "password" : "mypass1234"
        }
      }
    },
    "UserUpdate" : {
      "type" : "object",
      "properties" : {
        "email" : {
          "type" : "string",
          "description" : "A unique email address."
        },
        "password" : {
          "type" : "string",
          "description" : "Password."
        }
      },
      "description" : "Update user information.",
      "example" : {
        "application/json" : {
          "email" : "new_email@acme.com"
        }
      }
    },
    "User" : {
      "type" : "object",
      "required" : [ "email", "id" ],
      "properties" : {
        "email" : {
          "type" : "string",
          "description" : "A unique email address."
        },
        "id" : {
          "type" : "string",
          "description" : "User Id."
        },
        "created_ts" : {
          "type" : "string",
          "format" : "date-time",
          "description" : "Server-side timestamp of the user creation.\n"
        },
        "updated_ts" : {
          "type" : "string",
          "format" : "date-time",
          "description" : "Server-side timestamp of the last user information update.\n"
        }
      },
      "description" : "User descriptor.",
      "example" : {
        "application/json" : {
          "email" : "user@acme.com",
          "id" : "806603def19d417d004a4b67e",
          "created_ts" : "2016-10-03T16:58:51.639Z",
          "updated_ts" : "2016-10-04T11:33:66.611Z"
        }
      }
    },
    "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" : "missing Authorization header",
          "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
        }
      }
    },
    "Settings" : {
      "type" : "object",
      "description" : "User settings."
    }
  }
}