# Notifications

Flaghand can notify an owner on devices they choose when drafts wait for approval or posts fail or are held. Notifications show counts, never post text. Tapping one opens the approval page or desk; it never approves or posts anything.

## Turn them on

Sign in as the workspace's owner, open **Settings → Account**, and under Notifications choose **Turn on** in the **This device** row. Allow notifications in the browser's own permission prompt. There is no extra permission dialog from Flaghand.

On iPhone, Web Push needs **iOS 16.4 or later** and the **Home Screen app**: use Safari's Share → Add to Home Screen, then open that app and turn notifications on in Settings. A regular Safari tab cannot subscribe. Browser and operating-system notification settings can prevent delivery even when a device is subscribed.

If permission was denied, change it in the browser's site settings before trying again. Unsupported browsers show an explanation instead of asking for permission. No device is subscribed by default, and sign-in or opening Settings never asks for notification permission.

## Your devices

Settings lists your subscribed devices in the current workspace. A server notification-key rotation does not replace an existing browser subscription or ask for permission again; that browser keeps its original identity, while new subscriptions use the current key. If an original signing key is temporarily unavailable, the device stays enrolled and its notification waits for the key to be restored.

Remove a device there to stop future sends and retries for that workspace. Its browser subscription may also serve another workspace, so removal does not invalidate the shared subscription. A notification already being delivered may still arrive. Removing a passkey also removes devices registered through it. Devices belong to one owner and workspace, not to every member.

The same owner-session API is documented in the [API reference](https://app.flaghand.com/docs/api.md):

- `GET /api/v1/workspaces/{workspace}/push-subscriptions` lists your devices, each device's public signing identity, and the current public application server key for new subscriptions.
- `POST /api/v1/workspaces/{workspace}/push-subscriptions` registers the subscription returned by this browser's `PushManager` after permission, with its `options.applicationServerKey` encoded as base64url in `vapid_public_key`.
- `DELETE /api/v1/workspaces/{workspace}/push-subscriptions/{id}` removes one of your devices.

These operations require an owner's signed-in session. API tokens cannot subscribe someone, inspect their devices or turn on notification permission. Agents continue to use approval requests and their returned `approval_url`; unattended requests notify only owners who already opted in.

## What is sent

Future approval requests and failed/held job transitions queue notifications. A burst is combined into one wakeup of each kind per device, with current workspace counts. Requests already approved before delivery don't cause an approval notification. Failed sends retry on the existing jobs cron; a push service's **404 or 410** deletes a dead subscription whose signing identity is known. Delivery is best effort: the browser, operating system and push service control availability and retention. An interrupted send can be delivered again.

The browser's push service transports an encrypted payload containing the product name, counts and an app URL, without draft ids, post text, approval notes or platform errors. Subscriptions and their browser encryption keys are encrypted at rest in Flaghand. The service worker only displays notifications and opens their app links; it does not cache the desk for offline use, approve, schedule or post.