Skip to content

Node Credentials

Every self-hosted Nexomatic service — a sink agent on a Linux box, a source engine in your data centre — authenticates to the Hub with a Client ID / Client Secret pair that belongs to a node row on the Nodes screen. The Nodes screen is the only issuer of these credentials: the Hub checks each credential against the rows in the portal database.

If a node row is deleted (for example by the platform janitor after the service stopped heartbeating for a long time), the service’s old credentials stop working and it will fail with UNAUTHENTICATED: Invalid credentials. The fix is to create a new node and point the service at its credentials — this guide covers exactly that.

  1. Open the Nodes screen in the portal.
  2. Click Create node and pick the node type your service runs as (a Linux sink runs as SELF_HOSTED_SINK (the platform’s container images run as PLATFORM_SINK_PYTHON / PLATFORM_SOURCE; match whatever the service was created with)).
  3. Copy the Client ID, Client Secret, and the node type’s UUID from the screen — the UUID goes into the service’s NODE_TYPE_UUID.

All services read their connection settings from environment variables:

VariableMeaning
CLIENT_IDClient ID of the node you just created
CLIENT_SECRETClient Secret of the node
NODE_TYPE_UUIDUUID of the node type the service registers as
HUB_HOST / HUB_PORTHub address (default localhost:50051)
SERVER_URLController HTTP URL (for config, binaries, and updates)
ROOT_FOLDERWorking directory — identity files live in <ROOT_FOLDER>/nexomatic_data/

The service unit is installed at:

/etc/systemd/system/nexomatic-sink.service

Two ways to update its credentials:

Option A — re-run the installer (rewrites the unit with the new values and restarts the service):

Terminal window
curl -fsSL https://<controller-url>/api/install-linux-service.sh | \
sudo bash -s -- --controller-url https://<controller-url> --client-secret <new-client-secret>

Option B — edit the unit directly, then reload and restart:

Terminal window
sudo nano /etc/systemd/system/nexomatic-sink.service
# update the CLIENT_ID, CLIENT_SECRET, and NODE_TYPE_UUID Environment= lines
sudo systemctl daemon-reload
sudo systemctl restart nexomatic-sink

Set the same variables in whatever environment your service launches from (shell profile, .env file, container environment, or systemd unit), then restart it.

A service persists its node identity in <ROOT_FOLDER>/nexomatic_data/node_uuid. When moving a service to a brand-new node, deleting this file is recommended so the old identity can’t cause confusion:

Terminal window
sudo rm /opt/nexomatic-sink/nexomatic_data/node_uuid # Linux sink installs

(With valid new credentials the Hub’s authentication takes over anyway, but a clean slate avoids revival edge cases.)

Restart the service and check the Nodes screen. The node should flip to ONLINE within a couple of minutes — the Hub flushes heartbeats to the database every ~2 minutes. Check the service log for errors meanwhile:

Terminal window
journalctl -u nexomatic-sink -f
SymptomCauseFix
UNAUTHENTICATED: Invalid credentialsNo node row matches the configured Client ID / Secret — the row was deleted, or a typoCreate a new node and update CLIENT_ID / CLIENT_SECRET
NOT_FOUND on registrationNODE_TYPE_UUID doesn’t match an existing node typeCopy the UUID from the Nodes screen
Node stays OFFLINEHeartbeats aren’t reaching the HubCheck HUB_HOST / HUB_PORT, network, and the service log
Node disappears after weeks of uptimeThe service stopped heartbeating (crash, network cut) and the janitor pruned the stale row — expected behaviourRe-credential the service using this guide

See also Sinks & Placement and the platform install guides under Sinks.