Security & licensing
How trust flows through a swarm: one cloud key per site, a broker that denies by default, sealed over-the-air enrolment, and licensing that follows the units you actually run.
The cloud key
Every swarm is gated by one cloud key. It is the swarm's licence and the credential each of its units uses to reach the hosted cloud. A key has two parts joined by a dot, key_id.secret:
4f2a9c1e0b.7d3f5a20c8...e91a
└────┬────┘ └──────┬──────┘
key_id secret| Part | Public? | Role | How it's stored |
|---|---|---|---|
key_id | Yes | Your swarm's tenant id and the topic prefix for its messages (ybm/{key_id}/) | In the clear |
secret | No | The password units authenticate with | Only its SHA-256 hash |
When you mint a key in your dashboard, we show you the full key_id.secret string exactly once and store only the SHA-256 of the secret. The plaintext is never written to a URL and can never be read back. See concepts for how keys map to swarms.
Treat the cloud key like a password. It is shown once, it is never recoverable, and anyone holding it can join that one swarm. If a key is lost or exposed, revoke it and mint a fresh one.
The broker enforces access
Access is enforced at the message broker, not in application code, and it is deny-by-default: a connection reaches nothing until a matching credential has been provisioned, and it is confined to its own ybm/{key_id}/ space. The cloud's only job is to provision or remove that credential at runtime. This keeps the trust boundary small and consistent: every unit, in every swarm, is checked the same way.
Units connect to the broker over an encrypted TLS connection, and each unit is delivered the trust anchor it needs to verify the cloud during adoption — so credentials and telemetry are never sent in the clear.
Revoke is an instant cutoff
Because the broker is the gate, revoking a key takes effect immediately. Revoke it from the dashboard and every unit carrying that credential is dropped and cannot reconnect. There is no cache to expire and no per-device step to repeat.
Revoke = instant fleet cutoff. Revoking a cloud key severs the whole swarm at once. Use it the moment a key is compromised or a site is decommissioned, then re-key the units you want back online.
Sealed enrolment
You never have to type a key onto a unit if you don't want to. A factory-fresh unit adopts itself over the air:
Sealed hello
With no key yet, the unit announces itself with a sealed hello on the onboarding channel and lands in your Pending units list. Until it is adopted it can reach nothing but that narrow onboarding space.
An administrator adopts it
An administrator adopts the pending unit against one of your swarm keys. This opens a brief, operator-initiated window rather than leaving any standing access.
Sealed bundle delivered
The cloud packages that swarm's credentials into a sealed bundle and delivers it to the unit using authenticated encryption, so the payload is both confidential in transit and tamper-evident. The unit opens it, stores the key, and reconnects as a full member of the swarm.
To deliver that bundle the cloud must hold the swarm's secret, so unlike an operator password it is kept recoverable but encrypted at rest. It is decrypted only for the instant an adoption needs it.
Tenant isolation
Operators are scoped to their organisation. When you sign in you only ever see, and can only ever act on, your own swarms and their units. Keys, fleets, floorplans and walls from other organisations are never visible.
Adopting units from the shared pending pool is an administrator action. An administrator can adopt a unit onto any organisation's key, which is also how a unit is moved between organisations: re-adopt it onto the target organisation's key and it re-homes there. Tenants who prefer not to use the pool simply provision their own key onto a unit directly.
Licensing
Licensing follows the same one-key-per-swarm shape. A swarm is one licensed site, and its subscription is billed per swarm with the quantity tracking your active units — you pay for exactly the screens you run.
- Paid tier: the swarm cloud and automatic updates. Only units on an active subscription pull new packages.
- Always free: direct remote-in over ZeroTier. If you are not subscribed you can still reach a unit directly to manage it.
The cloud itself is fully hosted and managed — there is nothing to install, run, or maintain on your side. For how the cloud provisions keys, delivers bundles, and serves packages, see the cloud.