POST
Register push token

Overview

The client posts its FCM registration token on first launch (after the user grants notification permission) and again whenever FCM rotates the token. Calling this endpoint with a token that’s already on the user’s record refreshes its updatedAt (and re-orders it to “most recent”) — it does not insert a duplicate row. Per QUESTIONS.md §7.1, all tokens are treated as FCM registration tokens by the worker-side PushSender, regardless of the platform field. The platform is retained for analytics — iOS clients deliver their APNs payload through the same FCM pipeline (FCM forwards to APNs server-side).
Token storage is capped at 10 active tokens per user. When a registration would push the count above 10, the oldest token by updatedAt is evicted. This bounds the array size on the user document and matches typical “5–6 active devices per user” patterns observed at scale.

Authentication

Bearer <accessToken> required. requireAuth + requireOnboarded middleware applied.

Path parameters

None.

Query parameters

None.

Request body

Example payload

Response — 200 OK

Side effects

  • Upserts the (token) entry in the user’s pushTokens array with platform, createdAt (preserved on refresh), and updatedAt (always set to now).
  • If inserting would push the array above 10 entries, removes the oldest by updatedAt first.
  • Does NOT broadcast or enqueue anything else. The token only takes effect on the next push attempt.

Error responses

Example error — 400 VALIDATION_FAILED

See also

curl