Skip to main content
Version: Mosquitto 2.8

Connections

Connections API

Available API Paths​

Path: /api/connections​

Methods​

GET​

Returns a list of active connections

Responses

Status Description Response Content or Scheme
200 List of active connections 
{
  "id": {
    "type": "string",
    "description": "Connection id (must be unique)"
  },
  "name": {
    "type": "string",
    "description": "Connection text name (must be unique)"
  },
  "url": {
    "type": "string"
  },
  "credentials": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "password": {
        "type": "string"
      }
    }
  },
  "rejectUnauthorized": {
    "type": "boolean",
    "description": "If true will validate broker's certificate (property is considered only if TLS plugins is enabled)"
  },
  "ca": {
    "type": "object",
    "description": "CA certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded CA certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "cert": {
    "type": "object",
    "description": "Client TLS certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "key": {
    "type": "object",
    "description": "Client private key (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client private key",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "status": {
    "type": "object",
    "description": "Connection status of the broker",
    "required": [
      "connected",
      "timestamp"
    ],
    "properties": {
      "connected": {
        "type": "boolean",
        "description": "Specifies if the broker is currently connected"
      },
      "timestamp": {
        "type": "integer",
        "description": "Time when broker was connected to MMC"
      },
      "error": {
        "type": "object",
        "description": "Error that occured during connecting, if occured (Field is present only in case of an error)",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Error name"
          },
          "errno": {
            "type": "integer",
            "description": "Numerical id of the error"
          },
          "syscall": {
            "type": "string",
            "description": "Command that failed"
          },
          "address": {
            "type": "string",
            "description": "IP address of the broker"
          },
          "port": {
            "type": "integer",
            "description": "Port of the broker connection"
          }
        }
      }
    }
  }
}

Example

{
  "id": "mosquitto-dev",
  "name": "Development Server",
  "url": "mqtts://url.com:1883",
  "credentials": {
    "username": "admin",
    "password": "adminpassword"
  },
  "ca": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "cert": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "key": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "rejectUnauthorized": "true",
  "status": {
    "connected": "false",
    "error": {
      "code": "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
    }
  }
}
Status Description Response Content or Scheme
401 Access to resource is denied. User not authenticated (logged in) or session expired 
{
  "code": {
    "type": "string",
    "enum": [
      "UNAUTHORIZED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Unauthorized"
    ],
    "description": "Message of the error"
  }
}
403 Forbidden (Connection with the same name/id already exists | Maximum number of connections reached) | User does not have access permissions 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Not allowed",
      "Connection with the same name/id already exists",
      "Maximum number of connections reached",
      "Connection with either the same name or id already exists"
    ],
    "description": "Message of the error"
  }
}
404 Plugin is not enabled or not found 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_FOUND"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Plugin not found"
    ],
    "description": "Message of the error"
  }
}
500 An internal server error occured 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "An internal server error occurred",
      "Connection already exists but status of the connection not found. Config file might be malformed",
      "Any other error message"
    ],
    "description": "Message of the error"
  }
}

POST​

Creates a connection. Can be used by connectionManager or Admin roles. If a connection error occured on connection creation which is due to a misconfiguartion, a subsequent request with updated information might fix it

Parameters

Name Required Type Request Properties or Schema
body true object A connection object.

Properties:

{
  "id": {
    "type": "string",
    "description": "Connection id (must be unique)"
  },
  "name": {
    "type": "string",
    "description": "Connection text name (must be unique)"
  },
  "url": {
    "type": "string"
  },
  "credentials": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "password": {
        "type": "string"
      }
    }
  },
  "rejectUnauthorized": {
    "type": "boolean",
    "description": "If true will validate broker's certificate (property is considered only if TLS plugins is enabled)"
  },
  "ca": {
    "type": "object",
    "description": "CA certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded CA certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "cert": {
    "type": "object",
    "description": "Client TLS certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "key": {
    "type": "object",
    "description": "Client private key (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client private key",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  }
}

Example

{
  "id": "mosquitto-dev",
  "name": "Development Server",
  "url": "mqtts://url.com:1883",
  "credentials": {
    "username": "admin",
    "password": "adminpassword"
  },
  "ca": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "cert": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "key": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "rejectUnauthorized": "true"
}

Responses

Status Description Response Content or Scheme
200 List of all connections (active or inactive) 
{
  "id": {
    "type": "string",
    "description": "Connection id (must be unique)"
  },
  "name": {
    "type": "string",
    "description": "Connection text name (must be unique)"
  },
  "url": {
    "type": "string"
  },
  "credentials": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "password": {
        "type": "string"
      }
    }
  },
  "rejectUnauthorized": {
    "type": "boolean",
    "description": "If true will validate broker's certificate (property is considered only if TLS plugins is enabled)"
  },
  "ca": {
    "type": "object",
    "description": "CA certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded CA certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "cert": {
    "type": "object",
    "description": "Client TLS certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "key": {
    "type": "object",
    "description": "Client private key (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client private key",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "status": {
    "type": "object",
    "description": "Connection status of the broker",
    "required": [
      "connected",
      "timestamp"
    ],
    "properties": {
      "connected": {
        "type": "boolean",
        "description": "Specifies if the broker is currently connected"
      },
      "timestamp": {
        "type": "integer",
        "description": "Time when broker was connected to MMC"
      },
      "error": {
        "type": "object",
        "description": "Error that occured during connecting, if occured (Field is present only in case of an error)",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Error name"
          },
          "errno": {
            "type": "integer",
            "description": "Numerical id of the error"
          },
          "syscall": {
            "type": "string",
            "description": "Command that failed"
          },
          "address": {
            "type": "string",
            "description": "IP address of the broker"
          },
          "port": {
            "type": "integer",
            "description": "Port of the broker connection"
          }
        }
      }
    }
  }
}

Example

{
  "id": "mosquitto-dev",
  "name": "Development Server",
  "url": "mqtts://url.com:1883",
  "credentials": {
    "username": "admin",
    "password": "adminpassword"
  },
  "ca": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "cert": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "key": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "rejectUnauthorized": "true",
  "status": {
    "connected": "false",
    "error": {
      "code": "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
    }
  }
}
Status Description Response Content or Scheme
401 Access to resource is denied. User not authenticated (logged in) or session expired 
{
  "code": {
    "type": "string",
    "enum": [
      "UNAUTHORIZED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Unauthorized"
    ],
    "description": "Message of the error"
  }
}
403 Forbidden (Connection with the same name/id already exists | Maximum number of connections reached) | User does not have access permissions 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Not allowed",
      "Connection with the same name/id already exists",
      "Maximum number of connections reached",
      "Connection with either the same name or id already exists"
    ],
    "description": "Message of the error"
  }
}
404 Plugin is not enabled or not found 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_FOUND"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Plugin not found"
    ],
    "description": "Message of the error"
  }
}
500 An internal server error occured 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "An internal server error occurred",
      "Connection already exists but status of the connection not found. Config file might be malformed",
      "Any other error message"
    ],
    "description": "Message of the error"
  }
}

Path: /api/connections/{connectionId}​

Methods​

DELETE​

Deletes a specified connection and returns a list of remaining ones. Can be used by connectionManager or Admin roles

Parameters

NameLocationTypeRequiredDescription
connectionIdpathstringtrueId of the connection to be deleted

Responses

Status Description Response Content or Scheme
200 List of remaining connections (active or inactive) 
{
  "id": {
    "type": "string",
    "description": "Connection id (must be unique)"
  },
  "name": {
    "type": "string",
    "description": "Connection text name (must be unique)"
  },
  "url": {
    "type": "string"
  },
  "credentials": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "password": {
        "type": "string"
      }
    }
  },
  "rejectUnauthorized": {
    "type": "boolean",
    "description": "If true will validate broker's certificate (property is considered only if TLS plugins is enabled)"
  },
  "ca": {
    "type": "object",
    "description": "CA certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded CA certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "cert": {
    "type": "object",
    "description": "Client TLS certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "key": {
    "type": "object",
    "description": "Client private key (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client private key",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "status": {
    "type": "object",
    "description": "Connection status of the broker",
    "required": [
      "connected",
      "timestamp"
    ],
    "properties": {
      "connected": {
        "type": "boolean",
        "description": "Specifies if the broker is currently connected"
      },
      "timestamp": {
        "type": "integer",
        "description": "Time when broker was connected to MMC"
      },
      "error": {
        "type": "object",
        "description": "Error that occured during connecting, if occured (Field is present only in case of an error)",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Error name"
          },
          "errno": {
            "type": "integer",
            "description": "Numerical id of the error"
          },
          "syscall": {
            "type": "string",
            "description": "Command that failed"
          },
          "address": {
            "type": "string",
            "description": "IP address of the broker"
          },
          "port": {
            "type": "integer",
            "description": "Port of the broker connection"
          }
        }
      }
    }
  }
}

Example

{
  "id": "mosquitto-dev",
  "name": "Development Server",
  "url": "mqtts://url.com:1883",
  "credentials": {
    "username": "admin",
    "password": "adminpassword"
  },
  "ca": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "cert": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "key": {
    "data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
    "endoding": "base64"
  },
  "rejectUnauthorized": "true",
  "status": {
    "connected": "false",
    "error": {
      "code": "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
    }
  }
}
Status Description Response Content or Scheme
202 Connection was successfully created but when attempting to connect, an error occured 
{
  "code": {
    "type": "string",
    "enum": [
      "ACCEPTED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Connection created but could not connect. Reason \"<error message>\""
    ],
    "description": "Message of the error"
  }
}
401 Access to resource is denied. User not authenticated (logged in) or session expired 
{
  "code": {
    "type": "string",
    "enum": [
      "UNAUTHORIZED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Unauthorized"
    ],
    "description": "Message of the error"
  }
}
403 Forbidden (Connection with the same name/id already exists | Maximum number of connections reached) | User does not have access permissions 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Not allowed",
      "Connection with the same name/id already exists",
      "Maximum number of connections reached",
      "Connection with either the same name or id already exists"
    ],
    "description": "Message of the error"
  }
}
404 Plugin is not enabled or not found 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_FOUND"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "Plugin not found"
    ],
    "description": "Message of the error"
  }
}
500 An internal server error occured 
{
  "code": {
    "type": "string",
    "enum": [
      "NOT_ALLOWED"
    ],
    "description": "Name of the error"
  },
  "message": {
    "type": "string",
    "enum": [
      "An internal server error occurred",
      "Connection already exists but status of the connection not found. Config file might be malformed",
      "Any other error message"
    ],
    "description": "Message of the error"
  }
}