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

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.

Topic patterns

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

Every tag lists its own subjects in the Topics array of its register (DeviceHub tag list): Output/Raw is the value stream, Input/Value is the write subject, Output/WriteResponse is the reply, and Input/Command (devicehub.pollonce.<device>.<tag>) asks for an immediate read.

Writing a tag

Tag values are written over the bus, not the REST API: there is no REST endpoint for it.

1. Subscribe to devicehub.write_response.<device>.<tag>.
2. Publish {"value": <value>, "writeID": "<uuid>"} to devicehub.write.<device>.<tag>. value is JSON of the tag's type (1.6, true, "AUTO"); writeID is optional.
3. Read the reply:

{"success":true,"timestamp":1790192833628,"statusCode":0,"status":"Good","writeID":"BE26B124-186E-2060-A3F2-74DDFAEB9D10"}

writeID is echoed back, so a client with several writes in flight can match each reply to its request. success: false (with a non-Good status) means the device rejected the write.

Subscribe before you publish: the reply arrives within tens of milliseconds (17 ms measured on 4.0.15). Make sure the reply subscription is live first (send a NATS PING after the SUB and wait for the PONG), or the reply is published before anyone is listening and is lost.

litmus-cli le data write <device> <tag> <value> does all of this (cli-v0.11.0 or later; litmus-cli update to upgrade; see /cli.md).

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.

Permission errors do arrive: unlike a bad login, subscribing to or publishing on a subject outside the account's grants gets an explicit -ERR, in LE's own wording: permission denied for subscription to topic <subject>: no access ReadAccess for topic <subject>. Stock NATS says Permissions Violation instead, so clients that retry on errors should match on permission and treat it as permanent.

Detecting a dead connection: the broker answers PING with PONG, and the first PONG after CONNECT also proves the login was accepted. Long-running clients should send periodic PINGs and reconnect when PONGs stop; a half-open TCP connection otherwise waits forever.

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.

Related