Register push token
Me
Register push token
Register or refresh a device’s FCM push token for the authenticated user. Caps the user at 10 tokens with oldest-by-updatedAt eviction.
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 itsupdatedAt (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
| Field | Type | Required | Notes | Example |
|---|---|---|---|---|
token | string | yes | 1..4096 chars. The FCM registration token issued to the device by getToken() (or its native equivalent). | fcm_AAAA...truncated |
platform | enum | yes | ios or android (lowercase on the wire; stored as IOS/ANDROID in Mongo). Retained for analytics only — see callout above. | ios |
Example payload
Response — 200 OK
Side effects
- Upserts the
(token)entry in the user’spushTokensarray withplatform,createdAt(preserved on refresh), andupdatedAt(always set tonow). - If inserting would push the array above 10 entries, removes the oldest by
updatedAtfirst. - Does NOT broadcast or enqueue anything else. The token only takes effect on the next push attempt.
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | token missing/empty/over 4096 chars, or platform not in { ios, android }. |
| 401 | UNAUTHENTICATED | Missing, malformed, or expired access token. |
| 403 | ONBOARDING_INCOMPLETE | Caller has not finished onboarding. |
Example error — 400 VALIDATION_FAILED
See also
- Push notification fan-out — what the worker does with the tokens, including FCM 410-GONE cleanup.
- Unregister push token — explicit removal on logout / permission revoke.
- Toggle notification mute — global mute flag that the worker honours BEFORE consulting tokens.