Skip to main content

Access control list (ACL)

The access control list (ACL) manages access to topics for non-admin users, and for anonymous access (everyone/*). Each entry represents the access permissions for a user to a specific topic or topic pattern.

The ACL can be displayed or modified with the ntfy access command:

ntfy access                            # Shows access control list (alias: 'ntfy user list')
ntfy access USERNAME                   # Shows access control entries for USERNAME
ntfy access USERNAME TOPIC PERMISSION  # Allow/deny access for USERNAME to TOPIC

A USERNAME is an existing user, as created with ntfy user add (see users and roles), or the anonymous user everyone or *, which represents clients that access the API without username/password.

A TOPIC is either a specific topic name (e.g. mytopic, or phil_alerts), or a wildcard pattern that matches any number of topics (e.g. alerts_* or ben-*). Only the wildcard character * is supported. It stands for zero to any number of characters.

A PERMISSION is any of the following supported permissions:

  • read-write (alias: rw): Allows publishing messages to the given topic, as well as subscribing and reading messages
  • read-only (aliases: read, ro): Allows only subscribing and reading messages, but not publishing to the topic
  • write-only (aliases: write, wo): Allows only publishing to the topic, but not subscribing to it
  • deny (alias: none): Allows neither publishing nor subscribing to a topic

Example commands (type ntfy access --help for more details):

ntfy access                        # Shows entire access control list
ntfy access phil                   # Shows access for user phil
ntfy access phil mytopic rw        # Allow read-write access to mytopic for user phil
ntfy access everyone mytopic rw    # Allow anonymous read-write access to mytopic
ntfy access everyone "up*" write   # Allow anonymous write-only access to topics "up..."
ntfy access --reset                # Reset entire access control list
ntfy access --reset phil           # Reset all access for user phil
ntfy access --reset phil mytopic   # Reset access for user phil and topic mytopic

 

Example ACL:

$ ntfy access
user phil (admin)
- read-write access to all topics (admin role)
user ben (user)
- read-write access to topic garagedoor
- read-write access to topic alerts*
- read-only access to topic furnace
user * (anonymous)
- read-only access to topic announcements
- read-only access to topic server-stats
- no access to any (other) topics (server config)

 

In this example, phil has the role admin, so he has read-write access to all topics (no ACL entries are necessary). User ben has three topic-specific entries. He can read, but not write to topic furnace, and has read-write access to topic garagedoor and all topics starting with the word alerts (wildcards). Clients that are not authenticated (called */everyone) only have read access to the announcements and server-stats topics.

Back to top