Self-Hosted ntfy Access Control: Deny-All, a Topic per Alert Domain, Access From Your App (2026)

A phone that keeps buzzing after its owner lost access is the quiet failure. I lead Medusa and Frappe programmes at MithTech, a team of Frappe specialists in Bengaluru. The code below is the alert layer of one of our own platforms, a back office we built on Medusa (what Medusa gives you). It is ours, so I can show where it works and where it does not.

What does deny-all change on a self-hosted ntfy?

A new ntfy server is open: everyone can read and write every topic. Setting auth-default-access to deny-all reverses that. A request is refused unless a user, a topic and a permission say otherwise, so each person, your publisher and your admin become accounts, and every grant becomes a row (ntfy access-control docs).

# server.yml  (ntfy v2.30.0)
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
enable-signup: false   # the default; written so nobody turns it on

Whether to self-host at all is a separate decision; this post assumes you have made it.

Four facts from the docs and the source (release v2.30.0, read on 14 October 2026) shape the rest of this post.

• A row is a user, a topic or pattern, and a permission: read-write, read-only, write-only or deny. The most specific row wins: a named user beats everyone, a longer pattern beats a shorter one, and with no row the default applies (source).
• There are two roles, user and admin, and no groups. An admin skips the table, so never make someone an admin to fix a missing row. A group is a set of rows you write per person (the open request for groups).
• Deny-all gates publishing too. Your publisher needs write on every topic it uses, and a new topic fails until you grant it.
• A token is its user. An access token carries all of its user's access; ntfy has no narrower token yet.

Run 2.24.0 or later and keep topic names lower case. Before that release, on SQLite, a rule for secret also matched SECRET (release notes).

Why a topic per alert domain and not one for everyone?

Split topics when different people have to act on different alerts. On one of our platforms every alert once went to a single default topic, so everyone got everything and nobody could be held to a queue. Alerts now route by the first word of the event name into eight topics: kyc, orders, queue, ops, support, vendors, security and money. The routing table holds 68 alert types.

One rule does the routing, so a new event lands in the right topic without anyone annotating it, and an unknown prefix falls back to ops instead of going nowhere.

// trimmed from the real table; topic names shortened
const TOPIC_BY_PREFIX = {
  kyc: "kyc", bank_account: "kyc", demat_account: "kyc",
  order: "orders", investing: "orders",
  indicative: "queue",              // a customer waiting for a person to price
  wallet: "money",
  security: "security", ai: "security",
  admin: "ops", desk: "ops", customer: "ops",
  support: "support", vendor: "vendors",
}
export const topicForEvent = (name: string) =>
  TOPIC_BY_PREFIX[name.split(".")[0]] ?? "ops"

The queue came off the orders topic for one reason. Quote requests are work, and order alerts are reports; mixed together, the one alert someone must act on looked like the fourteen that had just happened.

One topic is also the right answer sometimes. Our own website sends its lead alerts to a single topic, with one reader and a publisher whose access is write-only, so a leaked token cannot read the lead history. Its rule is the reverse of the platform's, and it fits: adding an event type must never mean adding a topic.

How do you decide who may read which topic?

Tie each topic to the one permission that makes the alert useful, and to nothing else. Our map has eight topics and uses seven permissions from the app's own list. The queue is earned by quotes:price, not quotes:view, because pricing is the act, and a viewer who cannot price would only get a buzz.

A viewer reads 4 topics, an operator 6 and an admin 8. The whole map is one object:

export const TOPIC_CAPABILITY = {
  kyc:      "kyc:followup",
  orders:   "quotes:view",         // reports, not actions
  queue:    "quotes:price",        // pricing is the act
  ops:      "submissions:view",
  support:  "support:view",
  vendors:  "vendors:view",
  security: "operators:manage",    // admin only
  money:    "operators:manage",    // admin only
}

Security and money stay with admins, and nobody gets more than read. Nothing needs an operator to publish to an alert topic, and write on the security topic would let a compromised phone forge a security alert. A person's permissions are also not a flat role: they are the role's list, or a custom preset's, plus extra grants, minus denials, and a denial wins. The sync reads that resolved list, never the role name.

A guard test fails if a mapped permission does not exist or if a topic that alerts route to has no permission. A typo would otherwise create a topic nobody can ever earn.

How does a demotion take the alerts away?

Write the rows from the person's current permissions every time, and write a deny for every topic they have not earned. That is the whole sync. It creates the ntfy user if it is missing, grants read-only on each earned topic and denies each of the other managed topics. An inactive person earns nothing, so deactivation takes the same path as a demotion.

const earned = active ? topicsForCapabilities(capabilities) : []
if (!known.includes(username)) {
  password = generatePassword()          // shown once; ntfy keeps only a hash
  await admin("POST", "/api/users", { username, password, role: "user" })
}
for (const topic of MANAGED_TOPICS) {
  await admin("POST", "/api/access", {
    username, topic,
    permission: earned.includes(topic) ? "read-only" : "deny",
  })
}

Granting alone is the drift bug. Someone loses kyc:followup, keeps the old row, and keeps receiving identity alerts for months, because the two lists were only equal on the day they were written. In ntfy a call that sets a permission replaces the old row for that user and topic (source), so a deny overwrites a read-only. We chose a deny row over deleting the row because a deny stays visible: "why can't she see KYC?" has an answer.

The sync runs from one shared helper, and every invite and update goes through it, from the admin console and from the desk's own operator screen. Two copies of that policy, the code comment says, would be a security defect. Try it below. Pick a role and a change, then switch the sync mode to see each failure.

We ran all 180 states of it. With grant and deny, the phone matches the desk in every one of its 60. With grant only, the phone drifts in 46 of 60: every change that takes a topic away, which is 23 of the 30 changes. With the sync skipped, the two disagree in all 60.

A 12-check guard test keeps the design from decaying. It fails if the deny half is removed, if a write grant appears, if an inactive person still earns a topic, or if the removal helper deletes before it denies. It is static: it reads the source and matches patterns, so it proves the code has the right shape and not that a call reached the server.

What does a revoke not reach?

Five things can leave a person reading after the app says no. These are the gaps around the sync. We list them because a reader copying the design should test each one on their own system.

1. A stream that is already open. ntfy checks access when a request starts. An open subscription then sends messages and keepalives and is not checked again (middleware, stream loop). In ntfy's own admin API, deleting a user or deleting a row ends the stream, and setting a deny row has no such call (source). Our app sends a deny. We have read this and not yet run it.
2. A call that fails. The sync does not block the change. On an update a failure is logged loudly and the update still succeeds, with no retry and no job that compares the two lists. A phone-alerts outage should not block adding a person, but the price is a revoke that quietly did not happen (the same boundary, for workflows).
3. A screen that never calls the sync. Editing a role preset changes what everyone on it can do in the desk on their next request. At the commit we read, 20 September 2026, that screen did not call the sync, so those people kept their old rows until their next invite or update.
4. A helper nothing calls. We wrote a function that denies every topic and then deletes the ntfy user, in that order, so a failed delete still leaves access gone. Nothing calls it and there is no delete route, so deactivation is the working revoke.
5. A catch-all outside the map. The default topic receives test sends and any alert whose own topic returned 403, and no permission earns it. Decide who may read it.

Test the first one on your version. The admin endpoints below exist in the v2.30.0 source and are undocumented, so pin your version.

# 0. as an admin: give the person read-only on the topic
curl -u admin:PASSWORD -X POST https://ntfy.example.com/v1/users/access \
  -d '{"username":"person@example.com","topic":"kyc","permission":"read-only"}'

# 1. an open stream, as the person
curl -u person@example.com:PASSWORD -s https://ntfy.example.com/kyc/json

# 2. as an admin, in a second terminal: set a deny row
curl -u admin:PASSWORD -X POST https://ntfy.example.com/v1/users/access \
  -d '{"username":"person@example.com","topic":"kyc","permission":"deny"}'

# 3. does stream 1 end? Then repeat with the row deleted:
curl -u admin:PASSWORD -X DELETE https://ntfy.example.com/v1/users/access \
  -d '{"username":"person@example.com","topic":"kyc"}'

The command-line tool is different: it edits the database directly and the running server is not told. With the optional ACL cache on, the server learns on the next reload, every 87 seconds by default (config docs).

What breaks when you add a topic under deny-all?

A new topic drops its alerts until the publisher is granted write on it. Deny-all gates publishing as well as reading. The first alert returns 403, the publisher logs a failed send, and nothing else happens: no alert about the missing alert. It cost us twice in two days. The first split into topics lost three alerts on 15 July 2026, and the queue topic followed on 16 July.

Our fix has three parts. On a 403 the alert goes to the default topic with the intended topic in its title, so it is loud and wrong instead of silent. The log records the topic the alert actually reached, not the one it meant. And a probe sends one message to every topic after any change.

Frequently asked questions

What is the bottom line?

The server settings take ten minutes. The work is the list you keep beside them, and making sure it changes whenever the other list does. Write the map, deny what is not earned, and test the revoke before you need it.