Accounts — serializers¶

Responsibilities¶

The accounts serializers define the API contract for:

authentication and password flows
workforce profile and personal settings
work schedule read/write payloads
device/session data returned to clients
invite creation, preview, acceptance, and management
skills and user-skill assignment operations
the aggregated me payload

They are responsible for:

validating incoming request data
normalizing user input
shaping response payloads for frontend clients
exposing derived/read-only fields where useful
keeping view logic thin

They are not responsible for business workflows that have been moved into services, such as invite lifecycle handling or auth session mutation.

Main serializers¶

LoginSerializer¶

Validates login requests for username-or-email authentication plus device context.

Fields
identifier
username
password
device_id
platform
device_name
app_version
push_token
Validation
Requires either identifier or username
Normalizes both into identifier
Strips whitespace
Normalizes platform
Used by
LoginView

This serializer exists partly for backward compatibility: older clients can still send username, while newer clients can send identifier.

LogoutSerializer¶

Validates logout requests.

Fields
refresh
Validation
Requires a non-empty refresh token
Used by
LogoutView

ChangePasswordSerializer¶

Validates authenticated password change requests.

Fields
current_password
new_password
new_password_confirm
Validation
Confirms current password is correct
Confirms new password and confirmation match
Runs Django password validators
Used by
ChangePasswordView

This serializer enforces password-change rules before the auth service updates the stored password.

ForgotPasswordSerializer¶

Validates password reset request initiation.

Fields
email
Validation
Lowercases and strips email
Used by
ForgotPasswordView

This serializer intentionally stays simple because the endpoint always returns a generic response to avoid account enumeration.

ResetPasswordSerializer¶

Validates password reset completion.

Fields
uid
token
new_password
new_password_confirm
Validation
Confirms password match
Decodes the user id from uid
Validates the reset token
Runs Django password validators
Injects resolved user into validated_data
Used by
ResetPasswordView

This serializer is the bridge between the password reset link payload and the actual user account.

DeviceSessionSummarySerializer¶

Read-only summary serializer for active device sessions.

Fields
id
created_at
revoked_at
ip
user_agent
Used by
nested device responses

This serializer is intentionally limited and does not expose refresh_jti.

DeviceSerializer¶

Read serializer for registered devices.

Fields
id
device_id
name
platform
app_version
push_provider
push_token
notifications_enabled
timezone
last_seen_at
created_at
active_sessions
Derived fields
active_sessions from non-revoked DeviceSession rows
Used by
MyDevicesView
device upsert responses

This serializer gives the frontend enough information to render device/session management screens.

DeviceUpsertSerializer¶

Validates device registration/update payloads.

Fields
device_id
platform
device_name
app_version
push_provider
push_token
notifications_enabled
timezone
Validation
Requires non-empty device_id
Validates allowed platform choice
Normalizes platform and push_provider
Used by
UpsertDeviceView

DeviceSessionSerializer¶

Full read-only session serializer.

Fields
id
device
refresh_jti
created_at
revoked_at
ip
user_agent

This is useful internally, though most frontend-facing APIs should prefer the summary serializer.

UserProfileSerializer¶

Primary serializer for workforce profile read/write operations.

Fields
Basic identity/display
- display_name
- phone
- job_title
- avatar
- preferred_name
- pronouns
Localization
- timezone
- locale
- week_start
General profile
- bio
- department
- location
- employee_id
- start_date
Workforce fields
- employment_type
- employment_status
- manager
- manager_name
- manager_username
- home_base
- primary_region
- travel_radius_km
- has_company_vehicle
- driver_license_type
- can_travel_internationally
- availability_status
- is_dispatchable
- on_call
- assignment_notes
- emergency_contact_name
- emergency_contact_phone
- emergency_contact_relation
Workload
- minimum_weekly_hours
- effective_minimum_weekly_hours
Validation
Strips string fields
Prevents negative numeric values where not allowed
Prevents a user from being their own manager
Derived fields
manager_name
manager_username
effective_minimum_weekly_hours
Used by
UpdateProfileView
nested inside MeSerializer

This is the main operational serializer for workforce identity.

UserSettingsSerializer¶

Read/write serializer for user UI and preference settings.

Fields
language
theme
gradient
card_style
card_color
font_family
font_scale
accent
density
reduce_motion
preferences
Validation
Strips language value
Validates theme against allowed set
Used by
UpdateSettingsView
nested inside MeSerializer

NotificationPrefsPatchSerializer¶

Serializer for patching notification preference overrides.

Fields
preferences
Validation
Requires a non-empty dictionary
Restricts values to booleans
Used by
MeNotificationPreferencesView

This serializer keeps the patch payload small and explicit.

UserWorkDaySerializer¶

Serializer for one day in a user work schedule.

Fields
id
weekday
weekday_label
enabled
start_time
end_time
break_minutes
Validation
If enabled, requires both start_time and end_time
Enforces end_time > start_time
Ensures break_minutes does not exceed total work duration
Derived fields
weekday_label
Used by
nested inside UserWorkScheduleSerializer

This serializer protects schedule consistency at the API boundary.

UserWorkScheduleSerializer¶

Serializer for the full weekly work schedule.

Fields
id
default_break_minutes
updated_at
derived_weekly_hours
days
Validation
Ensures default_break_minutes >= 0
Custom behavior
Custom update() applies nested day updates by weekday
Derived fields
derived_weekly_hours
Used by
MeWorkScheduleView

This serializer gives the frontend a stable weekly structure and supports partial updates.

MeSerializer¶

Aggregated serializer for the current user.

Fields
id
username
email
first_name
last_name
is_active
profile
settings
Nested serializers
UserProfileSerializer
UserSettingsSerializer
Used by
MeView
BootstrapView

This is the main “who am I” payload consumed by the frontend after login or bootstrap.

SkillOutSerializer¶

Read serializer for skills directory data.

Fields
id
name
category
is_active
Used by
skill listing and read endpoints

This is intended for stable frontend lookup and search use.

SkillWriteSerializer¶

Write serializer for creating and updating skills.

Fields
name
category
is_active
Validation
Requires non-empty name
Strips whitespace
Used by
skill create/update endpoints

Permission enforcement remains in the view layer.

UserSkillOutSerializer¶

Read serializer for a user’s assigned skills.

Fields
id
skill
level
level_display
valid_from
valid_until
notes
Nested serializers
SkillOutSerializer
Derived fields
level_display
Used by
user-skill list and patch responses

UserSkillUpsertSerializer¶

Validates one item in a bulk user-skill replacement payload.

Fields
skill_id
level
valid_from
valid_until
notes
Validation
Ensures valid_until >= valid_from when both are set
Used by
UserSkillsReplaceSerializer

UserSkillsReplaceSerializer¶

Validates and applies replacement of a user’s complete skill set.

Fields
skills
Validation
Rejects duplicate skill_id entries
Ensures referenced skills exist
Custom behavior
save(user=...) replaces omitted rows and upserts included rows
Used by
user-skill bulk replace endpoint

This serializer still contains some write behavior; over time, this could move fully into a skills service if desired.

UserSkillPatchSerializer¶

Validates patch updates for one UserSkill row.

Fields
level
valid_from
valid_until
notes
Validation
Ensures date range is valid
Used by
single user-skill patch endpoint

InviteSerializer¶

Detailed read serializer for invite management responses.

Fields
id
invite_type
email
org_id
org_name
role
token
status
expires_at
created_at
created_by_id
accepted_at
accepted_by_id
cancelled_at
cancelled_by_id
Derived fields
status
Used by
invite create/resend/cancel responses

InviteListSerializer¶

List-friendly read serializer for invite overviews.

Fields
id
invite_type
email
org_id
org_name
role
status
expires_at
created_at
accepted_at
cancelled_at
Used by
invite listing endpoint

This is lighter than InviteSerializer and suited to admin list views.

CreateInviteSerializer¶

Validates invite creation requests.

Fields
invite_type
email
org_id
role
expires_in_days
Validation
Lowercases and strips email
Strips role
Resolves and injects org
Rejects missing or inactive organizations
Used by
invite create endpoint

The serializer validates input shape; duplicate detection and lifecycle rules are handled in the invite service.

AcceptInviteSerializer¶

Validates invite acceptance requests.

Fields
token
password
Validation
Ensures token shape is correct
Enforces minimum password length when provided
Used by
AcceptInviteView

This serializer supports both: - existing authenticated users - anonymous invite acceptance that must create a new account

InvitePreviewModelSerializer¶

Public-facing serializer for invite preview.

Fields
email_masked
org_name
invite_type
role
status
is_valid
expires_at
accepted_at
cancelled_at
Derived fields
email_masked
status
is_valid
Used by
InvitePreviewView

This serializer is intentionally safer than exposing the full invited email.

Serializer relationship overview¶

flowchart TD
    MeSerializer --> UserProfileSerializer
    MeSerializer --> UserSettingsSerializer

    UserWorkScheduleSerializer --> UserWorkDaySerializer

    UserSkillOutSerializer --> SkillOutSerializer
    UserSkillsReplaceSerializer --> UserSkillUpsertSerializer

    DeviceSerializer --> DeviceSessionSummarySerializer

    InvitePreviewModelSerializer --> InviteSerializer