A credential is what a device logs in with. Each device has at most one active credential. Secrets are shown once, when they are issued, and Hermetry stores only a hash. This page explains the three credential types and how to issue, rotate, replace and revoke them.
Managing credentials needs the permission Manage device credentials (administrators by default). LoRaWAN sensors, gateway children and polled devices have no credential of their own.
The three types
| Type | Shown as | How the device logs in | Secret |
|---|---|---|---|
| Access token | Access token | MQTT username = the token, empty password, any client ID. HTTP: Authorization: Bearer <token>. | 32 random characters, generated by Hermetry. |
| MQTT basic | MQTT basic (username and password) | A username and a password, optionally with a pinned client ID. A client ID alone never logs in. | A generated 32-character password, or one you choose. |
| X.509 certificate | X.509 certificate | A client certificate (mutual TLS); client ID = serial = certificate CN. | None stored: “The private key stays on the device; only the certificate fingerprint is stored.” |
The device’s profile must allow the type (Allowed authentication on the profile’s Transport & auth tab). A login with a type the profile does not allow is refused with CONNACK 5.
MQTT basic rules
| Item | Rule |
|---|---|
| Username | 1 to 128 printable characters without spaces. Unique on the whole platform. provision is reserved. |
| Client ID (optional) | 1 to 64 characters from A–Z a–z 0–9 . _ : -. When pinned, the device must use it. |
| Generated password | 32 characters. Leave the password out to get one. |
| Chosen password | At least 16 characters (your organisation may require more, up to 128: Minimum length of a chosen MQTT password in Devices > ⋯ > Settings), at least 8 different characters, not a repeated or keyboard pattern, not a common password (also when padded with digits or symbols), and not containing the username or client ID. |
A refused password names the reason (too_short, too_few_distinct, pattern, common, contains_identifier), never the password.
X.509 rules
The certificate must be issued by the Hermetry device certificate authority, be active, belong to your organisation, and carry the device serial as CN. Licensed devices get it when you claim them. Uploading certificates from your own CA is not available. See Device certificates.
When a credential is issued
| Situation | What the device gets |
|---|---|
| New device with Issue an access token for new devices on (the default) | An access token, shown once in the drawer. |
| New device with that setting off | No credential. Set one through the API. |
| Bulk import | An access token or MQTT basic per row; the passwords and tokens are in a credentials file you can download once, within 15 minutes. See Importing devices in bulk. |
| Self-provisioning | The credential returned in the provisioning answer. |
| Claiming a licensed device | Its X.509 certificate. |
The Credentials tab
Open the device and its Credentials tab. It is shown to administrators, for devices that log in themselves. It lists the Type, the Client ID, Username, Fingerprint (SHA-256), Subject and Expires where they apply, and when the credential was Created and Last rotated. Below it, the Connection details card shows how the device logs in, with a placeholder where the secret goes. If the device has no credential, the tab says “The device has no active credential.”
Rotate the secret
- Select Rotate secret.
- Confirm Rotate the secret?: “The old secret stops working at once and the device disconnects until it is updated.”
- The New secret appears once, with Show, Hide and Copy, and the connection lines filled in with it. Copy what you need, then select I have stored it.
Rotation issues a new secret of the same type: a new token, or a new password for the same MQTT username.
Replace, switch or revoke (API)
The tab offers rotation. Replacing the credential with another type, and revoking it, are done through the API with the same permission:
| Call | Effect |
|---|---|
GET /tenant/{tenantId}/api/iot/devices/{deviceId}/credentials | The active credential: type and identifiers, never a secret. null when revoked. |
POST …/credentials/rotate | A new secret of the same type, returned once. |
PUT …/credentials | Replaces the credential with the one in the body. A generated token or password is returned once (secret). |
DELETE …/credentials | Revokes the credential. The device can no longer log in. |
Bodies for PUT:
{"type": "ACCESS_TOKEN"}{"type": "MQTT_BASIC", "username": "pump-07", "clientId": "pump-07", "password": null}{"type": "X509_CERTIFICATE", "certificateId": "6f1c…"}A password of null (or left out) gets a generated one. Answers carry Cache-Control: no-store.
What happens on every change
- Rotate, replace and revoke end the old credential at once. There is no grace period.
- Every open session of the device ends at once, on every broker node.
- The change is written to the audit log and the device’s Log tab (Credential rotated, Credential replaced, Credential revoked).
- The webhook event
device.credentials_rotatedis sent withchange:rotated,replaced,renewedorrevoked. It carries ids and safe fields only, never a credential.
Plan rotations: update the device first if it can take a new secret remotely (for example through a configuration channel you control), or be ready to update it by hand.
Good practice
- One credential per device. Never copy a token from one device to another; the second login takes over the first device’s session.
- Prefer generated secrets. Choose a password only when the firmware must carry a fixed one.
- Rotate secrets that were pasted into tickets, chats or scripts.
- Revoke the credential of a device you take out of service, or delete the device.
- Keep tokens out of URLs. Use Token in the URL only for devices that cannot send headers.
- Watch the “new network” notices: a device logging in from an unexpected network may mean a leaked credential.