Username format

Understanding the username@organization_id format required for CloudSignal MQTT connections.

CloudSignal uses a special username format to route connections to the correct organization. Understanding this format is critical for successful connections.

The format

Every MQTT connection to CloudSignal requires this username format:

username@organization_id

Component	Description
`username`	The name you set when creating the client
`@`	Required separator
`organization_id`	Your unique organization UUID

Example

Dashboard username:    agent-001
Organization ID:       a1b2c3d4-e5f6-7890-abcd-ef1234567890

Full connection username: agent-001@a1b2c3d4-e5f6-7890-abcd-ef1234567890

Why this format?

CloudSignal is a multi-tenant platform where many organizations share the same MQTT infrastructure. The @organization_id suffix:

Routes your connection to your organization's isolated space.
Applies the correct ACL rules for your clients.
Enforces your plan's quotas (connections, messages, and so on).
Keeps your data separate from other organizations.

Without the organization ID, the broker cannot identify which organization you belong to.

Finding your organization ID

In the dashboard

Go to Settings → Organization.
Copy the Organization ID field.

From an API response

If you use the CloudSignal API, the organization ID is returned when you authenticate:

{
  "organization": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Company"
  }
}

Common mistakes

The following formats fail authentication:

Pattern	Why it fails
`agent-001`	Missing `@organization_id` suffix
`agent-001@`	Empty organization ID
`agent-001 @ a1b2c3d4...`	Spaces around the `@`
`agent-001@a1b2c3d4...xyz`	Incomplete or incorrect organization ID

The correct form is the full username with the complete organization ID:

agent-001@a1b2c3d4-e5f6-7890-abcd-ef1234567890

Token service clients

If you're using the Token Service to create temporary clients, the same format applies. The token service creates short-lived MQTT clients that expire automatically.

Token username: temp_abc123
Full format:    temp_abc123@a1b2c3d4-e5f6-7890-abcd-ef1234567890

The token service response includes the full username ready to use:

{
  "mqtt_username": "temp_abc123@a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mqtt_password": "generated-password",
  "expires_at": "2024-01-15T12:00:00Z"
}

Code examples

Store organization ID

Store your organization ID as an environment variable:

# .env file
CLOUDSIGNAL_ORG_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
MQTT_USERNAME=agent-001
MQTT_PASSWORD=your-secure-password

JavaScript

const mqtt = require('mqtt');

const orgId = process.env.CLOUDSIGNAL_ORG_ID;
const username = process.env.MQTT_USERNAME;
const password = process.env.MQTT_PASSWORD;

const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  username: `${username}@${orgId}`, // Combines to full format
  password: password,
});

Python

import os
import paho.mqtt.client as mqtt
import ssl

org_id = os.environ['CLOUDSIGNAL_ORG_ID']
username = os.environ['MQTT_USERNAME']
password = os.environ['MQTT_PASSWORD']

client = mqtt.Client()
client.username_pw_set(f'{username}@{org_id}', password)
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.connect('mqtt.cloudsignal.app', 8883)

C# / .NET

var orgId = Environment.GetEnvironmentVariable("CLOUDSIGNAL_ORG_ID");
var username = Environment.GetEnvironmentVariable("MQTT_USERNAME");
var password = Environment.GetEnvironmentVariable("MQTT_PASSWORD");

var mqttClient = new MqttFactory().CreateMqttClient();
var options = new MqttClientOptionsBuilder()
    .WithTcpServer("mqtt.cloudsignal.app", 8883)
    .WithCredentials($"{username}@{orgId}", password)
    .WithTls()
    .Build();

Troubleshooting

"Connection refused" or "Not authorized"

Verify the format is username@organization_id.
Check the organization ID is the complete UUID, not truncated.
Verify the password (passwords are case-sensitive).
Check the client exists in the dashboard.

"Bad username or password"

This usually means either:

Missing or incorrect @organization_id suffix.
Client doesn't exist in that organization.
Password is wrong.

Test the format

Use an MQTT client like MQTTX to test:

Create a connection.
Host: mqtt.cloudsignal.app.
Port: 8883 (SSL).
Username: your-user@your-org-id.
Password: your password.
Enable SSL.

If it connects, your format is correct.