Access Management Options per Cloud Subscription Plan

This reference compares HiveMQ Cloud authentication methods, authorization capabilities, and feature limits across Cloud Serverless, Starter, and Enterprise plans.

Authentication Methods

Method Serverless Starter Enterprise

Username and password

Client certificates (X.509 / mTLS)

Not supported

JSON Web Tokens (JWT)

Not supported

Only one method can be active per cluster at a time for a Starter plan cluster. In a Starter plan cluster, switching methods automatically deactivates the previous one and may disconnect currently connected clients. Enterprise plan clusters support all authentication methods.

JWT: Supported Registered Claims

Applies to Starter and Enterprise only. JWT is not supported on Serverless.

Claim Description

iss

Issuer: Identifies the principal that issued the token.

sub

Subject: Identifies the principal that is the subject of the token.

aud

Audience — identifies the recipients that the token is intended for.

iat

Issued at: The time at which the token was issued.

exp

Expiration time: The time after which the token must not be accepted.

scope

Scope: Specifies the access scope the token grants.

The Starter plan supports only these registered claims. If your use case requires custom or private JWT claims, contact HiveMQ to discuss your Enterprise plan options.

Authorization Models per Plan

Capability Serverless Starter Enterprise

Default permissions (Publish Only, Subscribe Only, Publish and Subscribe)

Custom permissions (user-defined topic filters)

Permissions assigned directly to a credential

✓ (one per credential)

Not supported

Not supported

Role-based access control (RBAC) (permissions grouped into roles)

Not supported

Multiple roles per credential

Not supported

Dynamic topic variables in permission topic filters

Not supported

Permission Fields (Starter and Enterprise)

On Serverless, a permission is a single selection (Publish Only, Subscribe Only, or Publish and Subscribe) applied to all topics (#).

On Starter and Enterprise, each custom permission configures the following fields:

Field Required Description

Topic Filter

Yes

Any valid MQTT topic filter. Wildcards + (single level) and # (multi-level) are supported.

Activity

Yes

One or both of: Publish, Subscribe.

QoS levels

Yes

One or more of: QoS 0, QoS 1, QoS 2. The permission applies only to the selected levels.

Retained messages

No

Whether the client may publish retained messages. Applies to publish permissions only.

Shared subscription group

No

Whether the client may join a shared subscription. If enabled, specify a group name or # to match all groups. Applies to subscribe permissions only.

Dynamic Topic Variables (Starter and Enterprise)

Dynamic variables in permission topic filters are resolved per-connection at authorization time. They are not supported on Serverless.

Variable Available with Resolved value

${mqtt-clientid}

Any method

The MQTT client ID from the CONNECT packet.

${mqtt-username}

Username and password

The username from the CONNECT packet.

${string-sub}

JWT

The sub claim from the validated JWT.

${string-aud}

JWT

The aud claim from the validated JWT.

${string-iss}

JWT

The iss claim from the validated JWT.

${string-scope}

JWT

The scope claim from the validated JWT.

${string-subject-common-name}

Client certificate

The Common Name (CN) from the certificate subject field.

${string-issuer-common-name}

Client certificate

The Common Name (CN) from the certificate issuer field.

Caching delays

Changes to credentials, permissions, and roles are cached. New values do not take effect immediately.

Change type Serverless Starter Enterprise

Credential changes (add or remove)

Up to 1 minute

Up to 1 minute

Up to 1 minute

Permission changes

Up to 5 minutes

Up to 5 minutes

Up to 5 minutes

Role changes

Not applicable

Up to 24 hours

Up to 24 hours

To force disconnection of clients using stale credentials or permissions before the cache expires, use the HiveMQ Cloud REST API or Control Center.