parent: /workflows/agents.md back_out_url: /workflows/agents.md

Workflow 17: Authenticate a NATS / DataHub Client

You are at https://api.litmus.io/workflows/authenticate-nats-datahub-client.md Parent: https://api.litmus.io/workflows/agents.md If this is the wrong workflow, back out to the index above.

17. Authenticate a NATS / DataHub Client

UI trigger: System -> Access Control -> Tokens -> Access Accounts (create the credential, grant topics) and NATS Proxy (expose the bus). The LE UI also shows the same key under DataHub.

Opens the device's internal NATS message bus (DataHub) to an external client. Provisioning the credential is five REST calls. Connecting with it then needs four LE-specific client settings, none of them guessable, and every one of them fails as a bare connection timeout rather than an error.

URL pattern

Provisioning calls are REST under {{edgeUrl}}/access/.... Auth is HTTP Basic: username is the API token ({{apiToken}}), password empty. See /le/agents.md#authentication.

The bus itself is NATS on port 4222, not HTTP, so the connection in step 6 cannot be issued from Postman or any HTTP client. Use a NATS client library.

Step table

Step	Name in Collection	Method	Endpoint	Key input	Output / what to capture
1	Enable NATS Proxy	`PUT`	`/access/proxy/enable`	--	`204`. External clients can now reach the bus. Until this succeeds nothing off-device connects
2	Create Access Account	`POST`	`/access/accounts`	`{"name": "api_access_account", "enabled": true}`	`{id, apikey}`. The `apikey` is the NATS credential -- capture as `{{access_account_api_key}}`
3	Add Read Topic	`PUT`	`/access/accounts/access/{apikey}?accessType=read&topics=<pattern>`	Pattern, e.g. `devicehub.alias.>`	`204`. Repeat once per pattern
4	Add Write Topic	`PUT`	`/access/accounts/access/{apikey}?accessType=write&topics=<pattern>`	Pattern	`204`. Skip entirely for a read-only consumer
5 (verify)	Account Current Access	`GET`	`/access/accounts/access/{apikey}`	--	`{"read": [">"], "write": null}`. Confirms the grants landed
6	(not an API call)	--	`nats://<device-ip>:4222`	See client settings below	A connected NATS client

Steps 3 and 4 key off the API key, not the account UUID. {{access_account_id}} from step 2 is only needed for the account-level operations in /le/system/access-control.md (enable, disable, reset, delete).

Client connection settings

What any NATS client library needs to be told, whichever language it is written in. All five are required together, and the last four are where LE differs from a stock NATS broker.

Setting	What to send	Why
Broker address	`nats://<device-ip>:4222`	See the address table below for the on-device cases
Username	The `apikey` from step 2	LE accepts the key only as a user/password pair
Password	The same `apikey` again, not empty	Both fields carry the same value. This is the part that is not guessable
TLS	Trust the device CA, or accept any certificate	The bus uses the same self-signed certificate as the REST API (`System > Network > Certificates`, see /le/system/network.md)
Missing `version` in INFO	Tolerate it	LE's INFO banner omits `version`. Strict clients that parse it as a semantic version throw mid-handshake

Calling from	Address	Note
Another host on the network	`nats://<device-ip>:4222`	Needs step 1 done and the port open in the device firewall
A container on the same device	`nats://172.17.0.1:4222`	The Docker bridge gateway. Inside a container `localhost` is the container, not the device
A process on the device	`nats://127.0.0.1:4222`	The internal bus directly. This is what the Node-RED `Datahub Connect` node uses

Topic patterns

Patterns use NATS wildcards: > matches any number of trailing tokens, * matches exactly one.

Pattern	Covers
`devicehub.alias.>`	Device tag traffic
`analytics.publish.>`	Analytics output
`>`	The whole bus

For the JSON shape of the messages that arrive on these subjects, see /reference/devicehub-message-format.md.

Failure modes

Token auth is silently dropped: sending the key as a NATS auth_token (the token field of the CONNECT protocol message) is valid NATS and is accepted by stock brokers, but LE neither honours nor rejects it. The login is discarded and the connection times out. Send the key as username and password instead.

Every failure looks like the same timeout: a wrong key, token-style auth, and the version parse error all present as a connection timeout. The gateway never answers -ERR 'Authorization Violation', so a timeout means "try the next hypothesis", not "the broker is down". The most common cause is a key from a different device: keys are per-device and are not portable.

Fail fast with an INFO preflight: a NATS broker greets every TCP connection with INFO and a JSON document before any TLS or authentication. Opening a raw socket and reading that one line tells you in under a second whether a broker is listening and whether auth_required is true, instead of spending one full timeout per credential guess.

No grants means no data: a new account has no grants at all, so a client with a correct key connects successfully and then receives nothing. Grant at least one read pattern (step 3) before concluding the connection is broken.

Port check: 4222 is the DataHub broker port and the NATS integration provider default. Field devices have also been seen with a firewall ACCEPT rule for TCP 4999 on eth0 labelled NATS (visible under System > Device Management > Templates > List Configuration Template Inventory in dm.firewall.rules). If 4222 refuses from off-device while the proxy is enabled, confirm which port your deployment publishes and open it under System > Network.

Task	Fetch
Rest of the access-account surface: `Reset Access Account` to rotate a leaked key, remove-topic calls, enable/disable pair	/le/system/access-control.md
Message payload shape on the bus	/reference/devicehub-message-format.md
Opposite direction of travel: point the device's own integration engine at an external NATS broker	/le/integration/provider-examples.md#create-instance---nats
Open the port in the device firewall	/le/system/network.md