Push Token
Data Entity
Description
Stores FCM (Android) and APNs (iOS) device push tokens for authenticated users, enabling the platform to deliver real-time push notifications to specific devices. Each record maps a user to a device token on a given platform, supporting multiple devices per user and lifecycle management (registration, refresh, revocation).
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key. Uniquely identifies a push token registration record. | PKrequiredunique |
user_id |
uuid |
Foreign key reference to the users table. Identifies which user this device token belongs to. | required |
token |
string |
The raw FCM registration token (Android) or APNs device token (iOS) issued by the platform provider. Tokens are long opaque strings (up to ~4096 chars for FCM). | required |
platform |
enum |
The mobile platform this token is valid for. Determines which delivery adapter (FCM or APNs) is used. | required |
device_id |
string |
A stable device identifier (e.g., Android Install ID or iOS identifierForVendor) used to associate a token with a physical device and enable upsert-on-refresh logic. Allows replacing an old token when FCM/APNs issues a new one for the same device. | - |
device_name |
string |
Human-readable device name (e.g., 'iPhone 15 Pro', 'Pixel 8') captured at registration for display in the session management screen. | - |
is_active |
boolean |
Whether this token is currently valid and eligible for delivery. Set to false on logout, explicit revocation, or after receiving an InvalidRegistration error from FCM/APNs. | required |
last_used_at |
datetime |
Timestamp of the last successful notification dispatch to this token. Used to identify and prune stale tokens that have not been used for an extended period. | - |
created_at |
datetime |
Timestamp when this push token record was first created (device first registered). | required |
updated_at |
datetime |
Timestamp of the last update to this record, including token refresh and is_active changes. | required |
Database Indexes
idx_push_token_user_id
Columns: user_id
idx_push_token_user_platform
Columns: user_id, platform
idx_push_token_device_id
Columns: user_id, device_id
idx_push_token_token
Columns: token
idx_push_token_is_active
Columns: is_active
Validation Rules
token_not_empty
error
Validation failed
platform_valid_enum
error
Validation failed
user_must_exist
error
Validation failed
token_globally_unique
error
Validation failed
device_id_unique_per_user
error
Validation failed
Business Rules
multi_device_per_user
A single user may have push tokens registered for multiple devices simultaneously. There is no enforced limit on the number of active tokens per user, enabling delivery to all logged-in devices.
upsert_on_token_refresh
When FCM or APNs issues a new token for an existing device (identified by device_id), the existing token record must be updated rather than creating a duplicate. If device_id is present, perform an upsert keyed on (user_id, device_id).
revoke_on_logout
When a user logs out of the mobile app, all push tokens associated with that user's current device must be deleted from the backend to prevent push delivery to unauthenticated sessions.
deactivate_on_provider_error
When the FCM or APNs adapter receives an InvalidRegistration, NotRegistered, or equivalent permanent error for a token, set is_active to false rather than deleting, to preserve the audit trail. Deactivated tokens are excluded from future delivery.
push_disabled_revokes_token
When a user disables push notifications in Notification Settings, all their active push tokens must be deleted from the backend to ensure no further push deliveries are attempted, complying with GDPR consent withdrawal.
update_last_used_on_send
Each time a notification is successfully dispatched via a token, the last_used_at timestamp must be updated. This supports stale-token pruning for tokens unused beyond a configurable threshold (e.g., 90 days).