11.5 Web push subscriptions

GET /api/v1/push-subscriptions

• Purpose. Reports whether browser push is configured and returns the public VAPID key.
• Authentication. Session cookie. Public users and staff with an active portal membership.
• Headers. None required beyond the cookie.

curl -s https://dffms.org/api/v1/push-subscriptions \
  -H 'Cookie: __Secure-dffms.session_token=<session-cookie>'

Response (200):

{
  "data": { "configured": true, "publicKey": "<vapid-public-key>" },
  "error": null,
  "requestId": "<request-id>"
}

Errors: 401 UNAUTHENTICATED. Side effects: none.

POST /api/v1/push-subscriptions

• Purpose. Stores the browser's push subscription for the signed-in account.
• Authentication. Session cookie; Origin must be allowed (assertTrustedOrigin).
• Body. The browser PushSubscription JSON:

Field	Type	Required	Rules
endpoint	string	Yes	Valid URL, max 2,048
keys.p256dh	string	Yes	32 to 512 characters
keys.auth	string	Yes	8 to 256 characters

curl -s -X POST https://dffms.org/api/v1/push-subscriptions \
  -H 'Cookie: __Secure-dffms.session_token=<session-cookie>' \
  -H 'Origin: https://dffms.org' \
  -H 'Content-Type: application/json' \
  -d '{"endpoint":"https://<push-service-host>/<subscription-id>","keys":{"p256dh":"<p256dh-key>","auth":"<auth-secret>"}}'

Response (201): {"data":{"subscribed":true},"error":null,"requestId":"..."}

Errors:

HTTP	Code	Meaning
401	UNAUTHENTICATED	No session or no portal access.
403	ORIGIN_DENIED	Origin not allowed.
413	PAYLOAD_TOO_LARGE	Declared length above 8 KiB.
422	VALIDATION_ERROR	Subscription fails validation ("Invalid push subscription").
500	INTERNAL_ERROR	Also returned for malformed JSON, because the body is parsed before validation and a parse error is not mapped.

Side effects: upserts a push subscription row for (tenant, user, endpoint). No audit event.

DELETE /api/v1/push-subscriptions

• Purpose. Removes the subscription for the given endpoint.
• Body. {"endpoint":"https://<push-service-host>/<subscription-id>"} (URL, required).
• Response (200). {"data":{"subscribed":false},"error":null,"requestId":"..."}
• Errors. 401, 403 ORIGIN_DENIED, 422 VALIDATION_ERROR (endpoint not a URL), 500 INTERNAL_ERROR (malformed JSON, as above).
• Side effects. Deletes the row matching the user and endpoint.