Credentials & secrets

The Domotz portal stores one set of credentials per device called Custom Driver Management (CDM) — a username / password pair that every driver assigned to that device can read.

Default: inherited from the portal

Drivers read the CDM credentials with:

var user = D.device.username();
var pass = D.device.password();

Every D.device.* protocol call — HTTP, SSH, SNMP v3, Telnet, WinRM, SCP — uses these automatically if you do not set username / password in the options.

D.device.sendSSHCommand({ command: 'uptime' }, callback); // uses CDM credentials

Per-call override

Override for one call by passing credentials in the options object:

D.device.sendSSHCommand({
    command: 'show version',
    username: 'read-only',
    password: 'something-else'
}, callback);

Useful when one driver needs to talk to the device with two different accounts — for example, a read-only account for polling and an admin account for the occasional write.

Parameter-driven secrets

When a driver needs a secret that the CDM slot cannot provide (API tokens, enable passwords, third-party bearer tokens), declare a top-of-file parameter:

/**
 * @description Device enable password
 * @type SECRET_TEXT
 */
var enablePassword;

The portal prompts the operator to fill this in when the driver is uploaded or when it’s assigned to a device. SECRET_TEXT values are encrypted at rest and masked in logs. The driver reads them by name — enablePassword is a global variable in the example above — or via D.getParameter('enablePassword').

See Driver lifecycle — Parameter declarations for the full parameter declaration syntax.

Never hard-code

Resist the temptation to put credentials in the driver source. It leaks them to everyone who can view the driver, fails rotation, and breaks the portal’s audit trail.

Read-only in the sandbox

The D.device.username() / D.device.password() functions return strings and cannot be modified. Changing the device’s CDM credentials happens in the Domotz portal, not at runtime.

Encrypting at rest

If you need to pass a secret between ticks (you usually do not), encrypt it with D.crypto and base64 it into a variable. This is unusual — most drivers are stateless — but it’s the pattern when a device hands you a short-lived token you need to reuse.