Device Authentication

Vwire uses two separate device credentials for MQTT authentication and topic routing.

---

Two credentials

Every Vwire device has an Auth Token and a Device ID. They serve different purposes:

Credential	Example	Format	Purpose
Auth Token	at_7f3a1c9e...	at_ + random hex	Authenticates the MQTT connection (the password)
Device ID	VW-ABC123	VW- or VU- + 6 chars	Identifies topics and routes messages

Both are available on the device detail page in the dashboard.

---

MQTT credential mapping

MQTT field	Value
clientId	Device ID (e.g. VW-ABC123)
username	Device ID (e.g. VW-ABC123)
password	Auth Token (e.g. at_7f3a1c9e...)

The broker validates the auth token (password) against the database. The Device ID (clientId) is used for MQTT ACL enforcement — the broker only allows the device to publish to topics beginning with vwire/{deviceId}/.

The Vwire library sets all three fields automatically when you call:

Vwire.config(AUTH_TOKEN);    // sets the password
Vwire.setDeviceId(DEVICE_ID); // sets clientId and username

---

What happens on bad credentials

Scenario	CONNACK code	Library log
Invalid auth token	5 (Not Authorized)	[Vwire] MQTT connect failed: 5
Device deleted or inactive	5 (Not Authorized)	[Vwire] MQTT connect failed: 5
Broker unreachable	timeout / code 3	[Vwire] MQTT connect failed: 3

On failure, the library backs off and retries after 30 seconds.

---

TLS / MQTTS

All production connections use TLS 1.2+ on port 8883 (MQTTS) against mqtt.vwire.io.
The broker's certificate is signed by a public CA — no client certificate is required.

// TLS connection (default — no extra config needed)
Vwire.config(AUTH_TOKEN);
Vwire.setDeviceId(DEVICE_ID);
Vwire.begin(SSID, PASSWORD);

---

Regenerating a token (if compromised)

1. Go to Dashboard → Device → Settings → Regenerate Token
2. Update AUTH_TOKEN in your firmware
3. Flash the updated firmware to the device

The old token is immediately invalidated and any active connection using it is forcibly disconnected.

---

Credential scheme

MQTT field	Value
clientId	The Device Token
username	The Device Token (same)
password	The Device Token (same)

All three MQTT connection fields carry the token. This is intentional — some MQTT clients require clientId and username to match.

---

Token format

Device Tokens are UUID v4 strings with a dt_ prefix:

dt_7f3a1c9e-2b84-4d6f-a913-c5e28f01b774

Tokens are:

• Unique per device — no two devices share a token
• Non-rotatable (currently) — if compromised, delete the device and recreate it
• Never transmitted in plaintext — always use MQTTS (TLS port 8883) or WSS

---

TLS / MQTTS

All production connections use TLS 1.2+ on port 8883 (MQTTS).
The broker's certificate is signed by a public CA — no client certificate is required.

// TLS connection
Vwire.begin(SSID, PASSWORD);

---

What happens on bad credentials

If the token is invalid or the device has been deleted:

• MQTT broker returns CONNACK with code 5 (Not Authorized)
• VWire library logs: [VWire] MQTT connect failed: 5
• The library backs off and retries after 30 seconds

---

Token rotation (when compromised)

1. Go to Dashboard → Device → Settings → Regenerate Token
2. Update the DEVICE_TOKEN constant in your firmware
3. Flash the updated firmware to the device

The old token is immediately invalidated — any active connection using it is forcibly disconnected.

---

Per-organization isolation

All VWire MQTT topics are namespaced by organization. Two organizations with identically named devices are completely isolated at the broker level.