All guides

How-to guides · 5 min

Issue and revoke credentials

Connector credentials let your device or gateway log in to the Lab broker and use its own topics. Here is how to issue them, store them safely, replace them and revoke them.

OBSERVE and CONTROL

CapabilityWhat it allows and who issues it
OBSERVEPublish state, telemetry and hello. Issued by an Owner, Admin or Developer. Selected by default.
CONTROLAlso publish receipt and receive commands on its own commands topic. Issued only by an Owner or Admin with explicit confirmation.

CONTROL credentials alone do not enable writes. Commands also need local write consent and a separate Owner/Admin consent in the Lab.

Issue credentials

  1. Open the source

    On an MQTT or Home Assistant source page go to the “Connector” section, “Connector credentials” panel. The simulator needs no credentials.

  2. Choose the capability

    In “Capability” keep OBSERVE if you only need telemetry. For CONTROL tick “I authorize this connector to receive bounded Lab commands”.

  3. Set the lifetime

    “Lifetime, seconds” is 60 to 604800 (seven days). The default is 86400, one day. Shorter is safer.

  4. Issue

    Click “Issue one-time credentials”. A “Save the private file now” block appears with the password and topics.

  5. Save the file

    Click “Download private file” (lab-credential.json). On POSIX give it mode 0600, on Windows a private ACL. Then click “Dismiss and clear secret”.

The password is shown only once. The Lab stores only its SHA-256 hash and cannot show it again. Never paste the password into a profile, ticket or chat. If the file is lost, issue new credentials with rotation.

Rotation

While active credentials exist, new ones are not issued without rotation. To replace them, tick “Rotate existing active credentials and revoke previous ones” and click “Issue one-time credentials”.

The Lab first closes the old credentials' access and disconnects their session, then creates the new ones. The new credentials have a new ID, username, password and topics. Update the file in your connector and restart it.

Revocation

  1. Click “Revoke”

    The button is next to credentials in the ACTIVE, PENDING or REVOKING state. Only an Owner or Admin can revoke.

  2. Confirm

    Click “Confirm revocation”. If the state stays REVOKING, you can safely revoke again.

Revocation closes connector access and requests restoration of an active command. It does not confirm measured restoration: check the evidence timeline.

The Lab also revokes credentials itself: when the lifetime ends, or when the issuer loses their role or invitation. To bind a new profile version to a source, no live credentials may exist.

Credential states

StateWhat it means
PENDINGIssuance is in progress. If interrupted, the Lab disables the credentials instead of activating them.
ACTIVEThe credentials work until the shown expiry.
REVOKINGLab access is already denied, but the broker has not confirmed cleanup yet.
REVOKEDRevoked and confirmed. Cannot be reactivated.
EXPIREDThe lifetime has ended.

Common problems

MessageWhat to do
active credential exists; explicitly rotate itTick rotation or revoke the active credentials first.
explicit bounded-control credential consent requiredFor CONTROL tick the confirmation under the form.
credential provisioning/revocation must reconcile firstA previous issuance or revocation has not finished. Refresh the page a little later.
isolated Lab broker is not configuredThe Lab broker is not configured. Contact the Lab administrator.
CONTROLThe option is missing because your role is Developer. Ask an Owner or Admin.