Connecting and disconnecting

Every client that wishes to send or receive messages must first connect to the messaging broker (using the CONNECT MQTT control packet), and can optionally disconnect at the end of its session (using the DISCONNECT MQTT control packet). To maintain the session, a client has to send a control packet to the broker within one and half times Keep Alive value. Otherwise, the client will be disconnected.

Where can I find an MQTT client / library?

Applications using the messaging service typically use an available client library providing MQTT functions for connecting to the broker, publishing messages, and subscribing to topics. There are MQTT libraries for many languages and environments. For example:

  • Mosquitto has downloads for Windows, Mac, and Linux. These include software libraries and command lines.
  • Paho provides clients for several languages, including Java, Python, and C/C++.
  • mqtt.js provides a javascript library which can be used from browsers (via websockets) and backend environments (native).
  • Xively provides a C Client Library with MQTT and TLS support for device firmware. In microcontroller environments, use of the Xively C Client Library is recommended.

See Xively Libraries for the full list of recommended libraries in the major languages, and more detail on the Xively embedded client in C.

What does "connecting" do?

Connecting to the broker refers to the creation of the TCP connection between the MQTT client (a device, user, or an application) and the broker. Normally, an MQTT client creates a connection, and the connection remains open indefinitely for the client to publish and receive messages.

There are three ways to connect to the Xively broker from an application. The method chosen depends on the application environment and needs.

Three ways to connect to the Xively MQTT broker

Native MQTT

This is the preferred method of connecting, and can be used when a client can make native connections. The Xively broker runs on ports 443 and 8883 (either port can be used). Port 443 may be suitable for devices on corporate networks with firewalls.


Websockets can be used when a client does not support native MQTT connections, such as a web browser. Port 443 is used.

Platform API (HTTPS)

Useful when a client does not have MQTT, or does not want to use MQTT. This method supports only the publishing of messages, and not subscribing, and is more suited to situations where a client publishes infrequently. The broker supports persistent HTTPS connections and HTTPS pipelining.

Connection modes

There are two possible ways to CONNECT to the MQTT broker:

1. Single-connection mode

  • The given client intends to only be connecting from one place
  • Any attempts to connect from another place with the same credentials will boot this connection
  • Clients in single-connection mode can CONNECT with Unclean sessions and retrieve any QoS1 messages that were sent on channels they were subscribed to at QoS1 since their last connection
id and username are both the id of the connector

2. Multi-connection mode

  • The given client intends to be connecting to the broker from many places at once.
  • The broker allows the same credentials to create up to 100 simultaneous connections from different locations, and reject the 101st connection.
  • The client uses JWT for authorization.

It is generally recommended that Devices connect in single-connection mode, both for security reasons (the device will immediately know if someone is trying to use its credentials because it has been booted), and so that it can retrieve messages it missed while disconnected if it is ever intentionally or unintentionally disconnected for a period of time.

Multi-connection mode is better suited for Users that are connecting to the messaging API (MQTT) from several places at once, such as simultaneously logging in and subscribing from multiple apps (a mobile app and a web app), or opening up several browser tabs at the same time.

You can't mix connection types

Connection types (single/multi) cannot be mixed by the same client. An attempt to do so will result in refused connections.

MQTT "Connect"

The broker requires all clients to use TLS encryption (mqtts). TLS1.2 is required, and should be explicitly requested by the client when possible (TLS1.0 and TLS1.1 are considered to be deprecated and platform support for these protocols may be removed in the future). Ciphers supporting forward secrecy are recommended. The ciphers currently supported by the broker can be seen with SSLLab's server test or with

nmap --script ssl-enum-ciphers -p 443

Broker connections are authenticated using standard MQTT fields for authentication: client ID, username, and password. The setting of these fields depends on the method used to connect to the broker, as well as the credentials being used (passwords or JWTs).

Calling parameters

Description and value

Broker port

Connection port for TLS communication
Must be set to 8883

Broker address / Hostname

Client ID

See below for what to use


See below for what to use


See below for what to use

Last Will

Clean / Unclean

Default value: Clean

Keep Alive

Default value: 60 seconds





Response Parameters


Connect notification

The CONNECTED confirmation is sent upon successfully connecting to a Xively server.
Common issues

  • Bad username or password: Check your credentials
  • Identifier rejected: Check your client id
  • Server unavailable: Check port or Xively status page

MQTT "Disconnect"

On disconnect, the network connection is closed.

No calling parameters or response parameters.

Messaging broker

Device Connection

Device connections use MQTT passwords. When a device connection is made, the clientID, username, and password must be set as follows:



Xively Device ID, assigned by the platform at time of provisioning


Xively Device ID


Device password, assigned by platform at time of provisioning

Application Connection with Native MQTT and Identity Service Credentials

When an application (user) connection is made using native MQTT and Identity service credentials, the clientID, username, and password must be set as follows:







The user's current JWT

When using Identity service credentials with the broker, the JWT must be current (not expired) at connect time. If the JWT is expired, the broker will return code 5 in the CONNACK message, and the application should obtain a current JWT before reconnecting.

Obtaining a new JWT on every reconnection is not recommended given the possibility of frequent connects/disconnects which can occur depending on network conditions between the application and the platform. Applications should check the return code, and obtain a new JWT only if required.

Application Connection with WebSockets

When an application (user) connection is made using websockets, the clientID, username, and password must be set as follows:







The CSRF token for the session. This is returned from the /auth/login endpoint.

In this case, the authentication credential (JWT) is sent in a cookie, and the CSRF token also is sent as a cookie.

Publishing using HTTPS

The Xively broker also accepts HTTP PUBs, which are advantageous for prototyping or applications where MQTT will not work. Read more about HTTP Publishing here.

Broker Clients

Broker clients may be devices, frontend applications, or backend applications. Frontend applications may connect to the broker to support direct messaging between devices and end users, for efficiency of interactive real-time product monitoring and control. Messages received could update the view's model directly. Backend applications may connect to the broker for messaging at the device population level, for example for data collection from multiple devices or messaging to any/all devices.

Topic naming

The Xively broker is highly integrated with the Identity and Blueprint services to provide security of message delivery. To enable this security, topic names use the following format:

xi/blue/v1/<accountId>/d/<deviceId>/<channel name>

where <accountId> is the Xively account ID, <deviceId> is the Xively device ID, and <channel name> is the name of one of the device channels.

A channel is a Xively platform concept (not MQTT). Channels can have flags attached to them to invoke additional platform features. For example, channels can be marked as time series. For time series channels, the platform retains a history of messages which can later be queried.

Publish and Subscribe

Messages can be published and subscribed at QoS0 or QoS1. Retain can be set on publish.

When designing applications for the Xively platform, it is important to consider the proper QoS setting for every type of message. If reliable message delivery is required for a message, both the publisher and the subscriber should use QoS1. In addition, the publisher and subscriber should set clean sessions to false when connecting to the broker.

When QoS1 is used, it is possible for duplication of messages to occur, in accordance with MQTT specifications. Applications may need to detect and drop duplicate messages depending on the impact of duplicates in the application environment.

QoS0 is appropriate when reliable delivery is not required, and the impact of lost messages can be tolerated by the application.

Application design needs to consider messages published on a topic may not be delivered to subscribers in the same order they were published.

What's Next

Now that we're Connected, learn about Publishing and Subscribing

Publishing and Subscribing

Connecting and disconnecting