Device Token
Data Entity
Description
Stores the FCM push notification token for a user's registered device. Tokens are registered on login and refreshed automatically by Firebase when they rotate. Multiple tokens per user are supported for multi-device scenarios. Tokens are deleted from Supabase on logout or when Firebase reports an invalid token response.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key, auto-generated UUID for each device token record | PKrequiredunique |
user_id |
uuid |
Foreign key referencing the authenticated user who owns this device token | required |
token |
string |
The FCM (Firebase Cloud Messaging) device registration token used to address push notifications to this specific device | requiredunique |
platform |
enum |
The mobile operating system platform this token was issued for, used to route via FCM (Android) or APNs bridge (iOS) | required |
registered_at |
datetime |
UTC timestamp when the token was first registered in Supabase, set on initial login or first token capture | required |
last_refreshed_at |
datetime |
UTC timestamp of the most recent token refresh. Updated by FCM token rotation callbacks. Allows detection of stale tokens and ordering when multiple tokens exist per user. | - |
is_active |
boolean |
Whether this token is currently considered valid. Set to false when Firebase reports TOKEN_NOT_REGISTERED or INVALID_REGISTRATION before the row is hard-deleted, providing a short grace window. | required |
Database Indexes
idx_device_token_user_id
Columns: user_id
idx_device_token_token_unique
Columns: token
idx_device_token_user_platform
Columns: user_id, platform
idx_device_token_is_active
Columns: is_active
Validation Rules
token_not_empty
error
Validation failed
platform_valid_enum
error
Validation failed
user_id_references_existing_user
error
Validation failed
token_max_length
error
Validation failed
registered_at_not_future
warning
Validation failed
Business Rules
multi_device_tokens_allowed
A single user may have multiple active device_token records simultaneously, one per registered device. There is no cap enforced at the database level; the application layer registers a new token per login on a new device.
delete_on_logout
When a user signs out, all device_token rows belonging to that user_id must be deleted from Supabase to prevent push notifications from being delivered to a session that is no longer authenticated.
delete_on_invalid_fcm_response
When FCM returns a TOKEN_NOT_REGISTERED or INVALID_REGISTRATION error code for a specific token, that token's row must be deleted from Supabase to keep the token table clean and prevent repeated failed deliveries.
upsert_on_token_rotation
When Firebase rotates a token (onTokenRefresh callback), fcm-token-manager must update the existing token row for the device (matched by old token value or device context) rather than creating a duplicate row.
token_global_uniqueness
The FCM token string must be globally unique across all users and devices. If an incoming token already exists under a different user_id, the conflicting row must be deleted before inserting the new record, as FCM tokens are device-bound and cannot be shared across accounts.
CRUD Operations
Storage Configuration
Entity Relationships
A user may have FCM push tokens registered across multiple devices simultaneously