Simplepush

Appearance

Topics ​

A topic is a named set of devices. Sending a notification or task to a topic delivers it to every device holding that topic.

bash
sp notify -t family --title "Dinner" --content "Ready at 7"
sp task -t eng-oncall --title "Build red on main" -c "Ack,Mute"

A topic value is a string of up to 255 characters with no whitespace. Anyone who knows the value can hold the topic. So an unguessable value works as the access control: share it only with the people who should receive.

Sending to your own devices needs no topic at all: just omit the topic.

Membership ​

  • Personal accounts: people join a topic by entering its value in the app. Whoever holds the value receives, and by default may also send. This is the flow for friends and family. Whoever you give the value to is trusted.
  • Organizations: an admin manages membership with sp org topics. Members are assigned and never join by themselves.

The sender must hold a shared topic to send to it. A personal send to a topic you are not a member of is rejected with 403 not_topic_holder.

Limits: a free account can create 1 topic, a paying account 20. A topic can have up to 10 holders, of which at most 3 can be free accounts.

Write-protected topics ​

By default any holder can also publish. Write-protection changes that. Everyone still receives, but publishing requires a sender token. This makes a topic safe to share widely: many receivers, a short list of authorized senders. Paying accounts can write-protect up to 2 topics. Set it up in the app under the topic's settings. The app then issues the sender token.

Senders present the token on every publish, via the Topic-Auth-Token header (or the topicAuthToken JSON field):

bash
curl -X POST https://api.simplepu.sh/v1/notifications \
  -H "API-Token: $SP_API_TOKEN" \
  -H "Topic: announcements" \
  -H "Topic-Auth-Token: $SENDER_TOKEN" \
  -H "Title: Maintenance window" \
  -H "Content: Saturday 02:00-04:00 UTC"

Publishing without a valid token fails with 401 write_protection_token_required / write_protection_token_invalid.

Encryption ​

Topic sends support end-to-end encryption. The key is derived from (password, topic-value). Everyone who has the password and the topic can decrypt, and the server never can. Pass -p "secret@your-topic" on the CLI or a [password, topic] pair in the SDKs. Organization topics are encrypted with the organization's master key instead. See Encryption for details.