Roles and Connection Authorization

Roles and Connection Authorization

Roles

Role	Can do
producer	register as producer, produce messages
consumer	register as consumer, subscribe/unsubscribe, ACK
both	all of the above (the default when unspecified)
manager	everything within its realm + realm administration (approve producers, manage keys/settings scoped to its realm)
admin	everything, across all realms (realm: "*"), + management commands

Roles are enforced per protocol event: e.g. a consumer-role socket that emits PRODUCER gets AUTH_FAIL { code: 403 }.

How each role gets connected

Only the manager role always requires manual authorization. Everything else is governed by per-realm settings:

"realms": {
  "acme": {
    "key": "consumer-pre-shared-key",   // consumers present this
    "require_acceptance": true          // producers must be accepted
  }
}

consumer (and both)

Present the realm's pre-shared key:

new Factory({ ..., auth: { realm: 'acme', role: 'consumer', key: 'consumer-pre-shared-key' } });

Automatically allowed when:

• the connection declares no realm, or
• the realm has no key configured, or
• the realm sets require_key: false.

Keys are managed with the set_realm_key command — from the Manager Tools. Generate/rotate/copy/clear are one click in the UI's realm row.

producer (and both)

Must be accepted into the realm before producing: the client submits an authorization request and a manager or admin approves it, which issues the client its token (see Authorization Requests). Producing without acceptance fails with 403.

Waived when the realm sets require_acceptance: false (or required: false — a fully open realm).

A both connection is subject to both rules — the key to connect and consume, acceptance to produce — each independently relaxed by the realm's settings.

manager

A manager connection is only possible with an approved or configured token — never a pre-shared key, never an open realm. Approval comes from an admin or an existing manager of the same realm via the authorization flow. Attempting AUTHENTICATION { role: 'manager' } without a token is rejected with 401 unconditionally.

admin

Configured tokens only (realm: "*", role: "admin"), typically the auto-generated TYO_MQ_ADMIN_TOKEN. Admin role is never granted to token-less connections, whatever the realm settings.

Decision table

Connection	Realm state	Result
consumer, no realm	—	allowed (realm default)
consumer, realm without key	—	allowed
consumer, realm with key	correct key sent	allowed
consumer, realm with key	wrong/missing key	AUTH_FAIL 401
producer, realm requiring acceptance	not accepted	AUTH_FAIL 403
producer, accepted (has token)	—	allowed
producer, realm require_acceptance: false	—	allowed
any role, realm required: false	—	allowed (role granted as requested)
manager, no token	anything	AUTH_FAIL 401

Legacy compatibility

Clients that authenticate with { token } only are completely unaffected by connection authorization. Token-less, role-declared authentication is an additive protocol — old clients keep working unchanged.