Understanding your organization
Learn how organizations, workspaces, and MQTT users relate to each other in CloudSignal.
When you sign up for CloudSignal, an organization is automatically created for you. This guide explains what that means and how the hierarchy works.
The CloudSignal hierarchy
A CloudSignal account has three nested concepts:
| Level | What it represents |
|---|---|
| Organization | The billing boundary. Everything you create lives inside one. |
| Workspace | Logical grouping within an organization (for example, dev, staging, prod). |
| MQTT user | Connection credential your apps and services authenticate with. Belongs to a workspace. |
| ACL rules | Topic permissions applied to the MQTT users in a workspace. |
| Team member | Person with dashboard access to the organization. |
What is an organization?
An organization is:
| Aspect | Meaning |
|---|---|
| Billing entity | Your subscription is attached to the organization |
| Top-level container | Everything belongs to an organization |
| Auto-created on signup | Named "[Your Name]'s Workspace" |
| Isolation boundary | Organizations are completely separate from each other |
Your organization was created automatically when you signed up. You can rename it in Settings → Organization.
Organization equals billing boundary
All usage within an organization counts toward a single subscription:
- All workspaces share the organization's quota.
- All MQTT users share the connection limits.
- Team members can be added to share access.
- One invoice covers everything.
Workspaces: logical separation
Workspaces subdivide your organization for different purposes:
| Use case | Example workspaces |
|---|---|
| Environments | development, staging, production |
| Projects | mobile-app, agent-fleet, backend |
| Clients | client-acme, client-globex |
| Teams | team-frontend, team-platform |
A default workspace is created automatically. You can:
- Rename it.
- Create additional workspaces.
- Delete it (if you have others).
MQTT users: connection credentials
MQTT users are the credentials your applications use to connect:
- Created within a workspace.
- Username format:
username@organization_id. - Each client or service should have its own user.
- Not the same as dashboard users (team members).
The two are distinct:
| Dashboard user | MQTT user |
|---|---|
| Logs into the web dashboard | Used by apps and services to connect |
| Manages the organization | Has topic permissions (ACL) |
| Invites team members | Created in the dashboard or via API |
Finding your organization ID
Your organization ID is needed when connecting:
- Go to Settings in the sidebar.
- Click Organization.
- Copy the Organization ID (UUID format).
The ID looks like: a1b2c3d4-e5f6-7890-abcd-ef1234567890.
Multiple organizations
You can belong to multiple organizations:
- Your own organization, created when you signed up.
- Invited organizations - others can invite you to theirs.
Switch between organizations using the organization selector in the dashboard header.
Practical example
A typical "Acme Corp" setup might look like this:
- Organization
Acme Corp- Workspace
Production- MQTT user
agent-gateway@acme-org-id - MQTT user
mobile-backend@acme-org-id - MQTT user
admin-dashboard@acme-org-id
- MQTT user
- Workspace
Development- MQTT user
dev-tester@acme-org-id - MQTT user
ci-pipeline@acme-org-id
- MQTT user
- Team members
alice@acme.com(Owner)bob@acme.com(Admin)carol@acme.com(Member)
- Workspace
Next steps
- Tour the dashboard - See where everything is
- Create an MQTT user - Set up your first connection credentials