Management Commands

Management Commands

All management writes go over the socket as signed commands: the caller proves possession of the admin token (or a realm manager key) with an HMAC-SHA256 signature over action + timestamp + nonce + body. The secret itself never crosses the wire; nonces are single-use (cluster-wide when clustering is enabled) and proofs expire after 5 minutes.

const { Authorization } = require('tyo-mq');
const response = await Authorization.authManagementCommand(adminToken, {
    command: '...', /* fields */
}, { host, port, protocol });

The interactive CLI (npm run manager) and the web UI wrap all of these — see Manager Tools.

Settings commands

Command	Fields	Effect
get	—	current auth + persistence settings (tokens masked to hashes, keys masked to *_configured flags)
set_global_auth	enabled	toggle auth globally
add_realm	realm, required?, manager_key?, key?, require_acceptance?, ephemeral?, ttl?	create a realm — permanent, or ephemeral/disposable with ephemeral: true + ttl (Ephemeral Realms)
rename_realm	from, to	rename a realm (tokens and live state follow)
remove_realm	realm	full disposal: config, scoped tokens, runtime state, connected sockets, stored messages + DLQ
set_realm_lifetime	realm, ephemeral, ttl?	convert between permanent and ephemeral; a fresh ttl extends the expiry (Ephemeral Realms)
set_realm_auth	realm, required	open/close a realm
set_realm_manager_key	realm, manager_key (empty clears)	realm operator credential
set_realm_key	realm, key (empty clears), require_key?	consumer pre-shared key
set_realm_acceptance	realm, required	producer admission requirement
set_external_auth	auth_url (empty clears), auth_secret?, realm? | realm_prefix?	external token validator — global, or scoped to one realm / a realm prefix (0.14.2; see Authentication and Realms)
revoke_token	token | token_hash | realm+client_id, allow_admin?	revoke issued tokens (admin tokens protected unless allow_admin)
set_persistence	storage, storage_options	hot-swap the storage backend

Settings changes persist to the loaded settings file and propagate to all cluster nodes. With the SQLite auth store enabled ([[Server Configuration]]), realms/tokens persist as row-level transactions instead of file rewrites.

Observability commands

Command	Fields	Returns
stats	—	live realm state: producers/consumers (total + online), subscription counts, current connections
dlq_list	realm?	dead-letter queue entries (all realms when omitted)
dlq_replay	msg_id, realm?	re-enqueues the message for its consumer, removes it from the DLQ, and delivers immediately if the consumer is online
dlq_discard	msg_id, realm?	drops the entry permanently

Authorization commands

These use their own socket events (same signing scheme):

• AUTHORIZATION_NEXT { body: { realm? }, proof } — oldest pending request
• AUTHORIZATION_DECIDE { body: { request_id, approved, role?, reason? }, proof }

Library wrappers: Authorization.nextAuthorizationRequest, decideAuthorizationRequest, nextRealmAuthorizationRequest, decideRealmAuthorizationRequest (the Realm variants sign with a realm manager key instead of the admin token). See Authorization Requests.

Scope rules

• Admin token — everything, every realm.
• Realm manager key — AUTHORIZATION_NEXT / AUTHORIZATION_DECIDE for its own realm only; all AUTH_MANAGEMENT_COMMANDs are refused.

Errors

Failed commands resolve with { ok: false, code, message } (the library wrappers reject with err.response carrying the same object): 400 bad fields · 401 invalid proof / reused nonce · 404 not found · 409 already exists · 501 backend lacks the capability.