Organization isolation

CloudSignal's multi-tenant model uses organization-based authentication, ACLs, and quotas to keep tenants completely separate.

CloudSignal uses organization-based isolation to keep tenants completely separate. Each organization has its own users, topics, ACLs, and quotas, which makes CloudSignal fit multi-tenant applications.

How it works

When you sign up for CloudSignal, an organization is automatically created:

Organization (org_k7xm4pqr2n5t)
- Users
  - admin@org_k7xm4pqr2n5t
  - agent-01@org_k7xm4pqr2n5t
  - webapp@org_k7xm4pqr2n5t
- ACL rules
  - agent-01: publish agents/agent-01/#
  - webapp: subscribe agents/#
- Sessions and messages
- Quotas (based on plan)

Username format

All CloudSignal usernames include the organization ID:

username@organization_id

For example:

agent-01@org_k7xm4pqr2n5t
dashboard@org_k7xm4pqr2n5t
api-service@org_k7xm4pqr2n5t

This format ensures users from different organizations never collide, even when they share the same local username.

Isolation guarantees

Complete data isolation

Messages published in one organization are never visible to another
Topic namespaces are entirely separate
Two organizations can both have a topic agents/agent-01/state, they're different topics

Separate ACL rules

Each organization defines its own access control:

# Organization A
user-a@org_a can publish to:   agents/#
user-a@org_a can subscribe to: commands/#

# Organization B (completely independent)
user-b@org_b can publish to:   agents/#   # Different namespace
user-b@org_b can subscribe to: data/#

Independent quotas

Quotas are enforced per organization.

Resource	Scope
Concurrent connections	Per organization
Messages per minute	Per organization
Retained messages	Per organization
Session storage	Per organization

One organization hitting its quota does not affect others.

Building multi-tenant applications

CloudSignal's organization model supports two multi-tenancy patterns.

Pattern 1: one organization per customer

Give each of your customers their own CloudSignal organization:

Your SaaS platform
- Customer A -> Organization org_customer_a
- Customer B -> Organization org_customer_b
- Customer C -> Organization org_customer_c

Aspect	Trade-off
Pros	Complete isolation, independent quotas, customers can manage their own users
Cons	Requires organization provisioning via API, separate credentials per customer

Pattern 2: topic-based isolation

Use a single organization with topic prefixes for isolation:

Your organization: org_your_saas
- Customer A topics: customer-a/#
- Customer B topics: customer-b/#
- Customer C topics: customer-c/#

Aspect	Trade-off
Pros	Simpler management (one organization), cross-customer queries are straightforward
Cons	ACL rules must enforce isolation, shared quota pool

For SaaS applications with strict isolation requirements, use one organization per customer. For internal applications, topic-based isolation is simpler.

ACL configuration

Access control lists (ACLs) enforce what each user can access:

# Agent can publish only its own messages
Username: agent-01@org_k7xm4pqr2n5t
  Publish:   agents/agent-01/#
  Subscribe: agents/agent-01/inbox

# Dashboard can read everything
Username: dashboard@org_k7xm4pqr2n5t
  Subscribe: agents/#
  Publish:   (none)

# Admin has full access
Username: admin@org_k7xm4pqr2n5t
  Publish:   #
  Subscribe: #

ACLs are configured in the CloudSignal dashboard or via API.

Security considerations

Credential isolation

Never share credentials between organizations. Each organization should have its own:

Credential type	Purpose
Admin users	Management and configuration
Service accounts	Backend integrations
Per-agent credentials	One credential per long-running client
Tokens	Browser clients (short-lived)

Audit logging

CloudSignal logs every authentication attempt and connection event per organization:

Successful and failed logins
Connection and disconnection events
ACL violations

Access logs in the dashboard under Session History.

API access

Organization management APIs require authentication:

# List users in your organization
curl -X GET "https://api.cloudsignal.app/v2/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

API keys are scoped to the organization that created them.

Migration and portability

CloudSignal speaks standard MQTT, so your application code isn't locked in:

Aspect	What this means
Same username format	Works across CloudSignal environments and most managed brokers
Exportable ACLs	Migrate your access rules with a one-shot script
Standard clients	Any MQTT 3.1.1 or 5.0 client connects without modification

If you need to migrate, your client code does not change, only the broker hostname.

How CloudSignal works - Core concepts
Configure ACLs - Set up access control

On this page