Reference

MokoNtfy CLI — groups, roles & protected topics

Details
Category: Reference
  • Applicable Software: MokoNtfy

MokoNtfy adds three server-side CLI commands for the access-control system introduced in 01.06.00, alongside the existing ntfy user and ntfy access. They are the command-line equivalent of the Site Administration pages.

Two of them run against the auth database directly (ntfy group and ntfy role) — they must run on the server host with access to server.yml / auth-file, and take no token. One runs against the live server over HTTP (ntfy protect) and needs --server plus an admin/owner --token.

ntfy group

Manage user groups and group topic access. A grant made to a group applies to every member. Group access is additive-only: a user's effective permission is the union of their groups' grants, so a deny/none permission is rejected — to subtract, add a per-user deny with ntfy access USERNAME TOPIC deny, which always wins.

ntfy group list                       # Show all groups, members and grants
ntfy group add GROUP                  # Create an empty group
ntfy group remove GROUP               # Delete a group (and its members/grants)

ntfy group member add GROUP USERNAME    # Add a user to a group (idempotent)
ntfy group member remove GROUP USERNAME # Remove a user from a group

ntfy group access GROUP TOPIC PERMISSION  # Grant topic access
ntfy group access reset GROUP [TOPIC]     # Remove one grant, or all of the group's grants

PERMISSION is one of read-write (alias rw), read-only (aliases read, ro), or write-only (aliases write, wo). TOPIC may include wildcards, e.g. "mytopic*". Aliases: add=a, remove=del/rm, list=l, access reset=r.

Examples

ntfy group add ops                    # Create group "ops"
ntfy group member add ops phil        # Add user phil to ops
ntfy group access ops alerts rw       # Grant ops read-write on "alerts"
ntfy group access ops "up*" write     # Grant ops write-only on "up..."
ntfy group access reset ops alerts    # Remove ops' grant for "alerts"
ntfy group access reset ops           # Remove all of ops' grants
ntfy group del ops                    # Delete ops

ntfy protect

Manage the protected-topics registry. A protected topic's ACL must be explicit — it is no longer reachable via the fall-through Everyone grant or the server default access (owners, admins and the reservation owner still retain access). This registry lives in the server's message-cache settings store, so unlike the other commands ntfy protect talks to the running server over its admin HTTP API (/v1/topics/protected). It therefore requires:

  • --server / -s — the ntfy server base URL (env NTFY_SERVER; default http://localhost:2586).
  • --token / -t — an admin/owner access token (env NTFY_TOKEN; create one with ntfy token add).
ntfy protect --token=TOKEN list                    # List protected topics
ntfy protect --token=TOKEN add TOPIC [--note=...]  # Mark a topic/pattern protected
ntfy protect --token=TOKEN remove TOPIC            # Unmark it

--note / -n records an optional reason with an added topic. Aliases: add=a/mark, remove=del/rm/unmark, list=l. Marking a topic protected removes its exact Everyone grant; a broader matching wildcard is left in place with a warning. Unprotecting does not re-grant Everyone access — reopen a topic deliberately with ntfy access.

Examples

ntfy protect --token=tk_... list
ntfy protect --token=tk_... add secret
ntfy protect --token=tk_... add "internal*" --note "staff only"
ntfy protect --token=tk_... remove secret

ntfy role

Manage RBAC roles — named bundles of capabilities (system-wide or topic-scoped) assignable to users or groups. Roles sit beside the coarse owner/admin/user role: admin and owner bypass every capability check, so roles gate delegated, non-admin access only. Role management is owner-only.

ntfy role list                                  # Show all roles, capabilities and assignments
ntfy role add ROLE                              # Create an empty role
ntfy role remove ROLE                           # Delete a role (caps + assignments)

ntfy role capability add ROLE CAPABILITY [SCOPE]    # Grant a capability (empty SCOPE = system-wide)
ntfy role capability remove ROLE CAPABILITY [SCOPE] # Remove a (capability, scope) grant

ntfy role assign ROLE (USERNAME|@g:GROUP)       # Assign to a user or a group
ntfy role unassign ROLE (USERNAME|@g:GROUP)     # Remove an assignment

A principal is either a username or a group in the @g:<group> form. A SCOPE is a topic name or * pattern (topic-scoped capabilities only); an empty scope is system-wide. Aliases: add=a, remove=del/rm, list=l, capability=cap.

Known capabilities: users.manage, acl.manage, groups.manage, branding.manage, tours.manage, approvals.manage, server.view, topics.acl.view, topics.protect.manage, topic.acl.manage, topic.protect.manage, topic.acl.view.

Examples

ntfy role add acl-delegate                                   # Create a role
ntfy role capability add acl-delegate topic.acl.manage "team-*"  # Topic-scoped capability
ntfy role capability add auditor topics.acl.view             # System-wide capability
ntfy role assign acl-delegate phil                           # Assign to user phil
ntfy role assign acl-delegate @g:ops                         # Assign to group ops
ntfy role unassign acl-delegate phil
ntfy role del acl-delegate

Where each command runs

  • ntfy group, ntfy role — auth-database-direct. Run on the server host; require auth-file in server.yml; no token.
  • ntfy protect — admin HTTP API. Can run anywhere that can reach the server; requires --server and an admin/owner --token.
Hits: 5

Owner, roles & access model

Details
Category: Reference
  • Applicable Software: MokoNtfy

MokoNtfy layers a small, explicit access model on top of ntfy. This reference explains the coarse role hierarchy, how ownership is protected and handed off, custom RBAC roles, and how it all composes with groups and protected topics.

The role hierarchy: owner > admin > user

Every account has one coarse role:

  • user — a normal account; access is governed entirely by topic ACLs (its own grants, group grants and the Everyone grant).
  • admin — bypasses every access-control check and can open the Site Administration area.
  • owner — the single highest account. An owner is a superset of admin (also bypasses every check) and additionally holds the owner-only powers, chiefly role management.

Both admin and owner bypass capability checks, so custom roles (below) only ever gate delegated, non-admin access.

How the owner role is minted

Owner is deliberately hard to obtain — it cannot be set like a normal role. The ordinary role-setting paths (creating a user, changing a role in the admin UI or via ntfy user change-role) accept only user or admin; owner is rejected there.

  • Bootstrap (one time). On a server with no owner yet, an existing admin is promoted with the CLI-only ntfy user set-owner USERNAME. This succeeds only while no owner exists and only if the target is already an admin.
  • Transfer (after that). Once an owner exists, ownership moves only through the ownership-transfer flow (POST /v1/account/owner/transfer), which hands the owner role to another admin. Trying to bootstrap again is rejected because an owner already exists.

Last-owner protection

There is always exactly one owner. The last owner cannot be demoted and cannot be deleted — both are blocked at the server. To step down, an owner transfers ownership to another admin first; the transfer itself performs the swap.

Custom roles (RBAC)

Beside the coarse role, an owner can define custom roles — named bundles of capabilities — and assign them to principals to delegate a slice of admin power without granting full admin.

  • Capabilities are either system-wide (empty scope) or topic-scoped (a topic name or * pattern, matched with the same wildcard rule as topic ACLs). System capabilities include users.manage, acl.manage, groups.manage, branding.manage, tours.manage, approvals.manage, server.view, topics.acl.view and topics.protect.manage. Topic-scoped ones are topic.acl.manage, topic.protect.manage and topic.acl.view — e.g. authority over team-* only.
  • Assignment targets a user or a whole group (in the @g:<group> form), so a role can be handed to every member of a group at once.
  • Role management is owner-only. Role CRUD and assignment are the anti-self-escalation guard, so only the owner sees the Roles card and can use it (or the ntfy role CLI). There is no delegable "manage roles" capability — it stays with the owner.

See MokoNtfy CLI — groups, roles & protected topics for the exact ntfy role syntax.

How it composes with groups and protected topics

For a user (admin/owner bypass all of this), a request on a topic is resolved by the real authorization engine in this shape:

  • Groups are additive. A group grant applies to every member; a user's effective topic permission is the union of their groups' grants. Group grants are read/write/read-write only — a group deny is not allowed.
  • Per-user grants win. A user's own explicit grant (including a per-user deny) always takes precedence over any group grant — that's how you subtract access that a group would otherwise give.
  • Protected topics require an explicit grant. A topic marked protected is no longer reachable through the fall-through Everyone grant or the server's default access; a matching user or group grant is required. Owners, admins and the topic's reservation owner still retain access.
  • Custom roles don't grant topic publish/subscribe access; they grant management capabilities (e.g. the ability to manage a topic's ACL or protect it). Access to send/receive on a topic still comes from the ACL grants above.

The admin Access preview resolves all of this for you: pick a user (or an anonymous visitor) and a topic and it reports read/write allowed or denied using the same engine.

Hits: 5

Subscribe to MokoNtfy (Web, Phone, CLI)

Details
Category: Reference
  • Applicable Software: MokoNtfy

You receive notifications by subscribing to a topic. A topic is just a name you choose; anyone who can publish to that topic (and is signed in) can send you notifications. Because topic names are visible to other users on the server, choose a name that cannot be easily guessed.

Note: MokoNtfy requires you to be signed in. If you don't have an account yet, contact Moko Consulting — self-registration is disabled. You can also sign in with Google (new Google sign-ins are approved by an administrator).

Web app

  1. Open ntfy.mokoconsulting.tech and sign in.
  2. Click Subscribe to topic, type your topic name (for example mytopic), and confirm.
  3. Messages published to that topic now appear in the web app.

Navigation & layout

Your topics are listed in a sidebar on the left. Click the logo in the top-left corner to collapse or expand that sidebar — useful for more reading room, and your choice is remembered between visits. On wide screens the top-left shows the full MokoNtfy wordmark; on narrow screens it shows the compact icon. The sign-in page shows the same wordmark above the form.

Background (web push) notifications

Background notifications via Web Push are enabled on this instance. Turn them on per browser under Settings; once enabled, notifications arrive even when the ntfy tab isn't focused. Support depends on your browser and OS — Chrome, Edge, Firefox, and Opera on desktop (while the browser is running), Safari 16.1+ on macOS 13+, Android with the browser closed, and iOS 16.4+ when the app is added to the home screen. If you leave background notifications off, keep an ntfy tab open (pinning the tab works well).

Per-topic notification level

From a subscribed topic's menu you can choose how noisy it is:

  • All messages (default) — every message notifies.
  • Important only — only high/urgent priority messages notify; the rest are still stored, just quiet. Applies both in the foreground and to background web push.
  • Muted — nothing notifies, and the topic is dropped from web push entirely.

Install as an app (PWA)

MokoNtfy is installable on desktop and mobile. Use your browser's Install app or Add to Home Screen option to get a standalone window, a launcher icon, and an unread badge. On an installed app, background notifications are always on (you can still mute individual topics).

Phone (Android / iOS)

  1. Install the ntfy app from Google Play, F-Droid, or the App Store.
  2. In the app, add a subscription and set the server to https://ntfy.mokoconsulting.tech (change the Default server in the app settings, or choose "Use another server" when subscribing).
  3. Enter your username and password for MokoNtfy so the app can access your topics.
  4. Subscribe to your topic name.

Command line (ntfy CLI)

Install the ntfy CLI, then subscribe and pipe each message to a script:

ntfy subscribe \
  --user <username> \
  https://ntfy.mokoconsulting.tech/mytopic

You can also run a command for every incoming message:

ntfy subscribe mytopic 'notify-send "$message"'

Next step

See Publish messages with MokoNtfy to send your first notification to a topic.

Hits: 8