Accounts — views¶

Responsibilities¶

The accounts views expose the HTTP API for identity, profile, device/session, invite, and skill workflows.

They are responsible for:

receiving requests and returning responses
applying authentication and permission classes
invoking serializers for request validation
calling service-layer functions for business workflows
selecting response status codes and payload structure

They are not responsible for:

storing business rules directly when a service exists
complex domain mutation logic
persistence-only concerns
frontend-specific presentation logic beyond stable API shape

In this app, views should stay thin and predictable.

Main views¶

`views.auth`¶

LoginView¶

Authenticates a user and creates a device-backed session.

Methods
POST
Permissions
AllowAny
Throttling
AnonRateThrottle
ScopedRateThrottle
scope: login
Request serializer
LoginSerializer
Service usage
services.auth.login_user
Response
access token
refresh token
device summary
Main status codes
200 OK
401 Unauthorized for invalid credentials

This is the primary login endpoint for web and mobile clients.

LogoutView¶

Revokes the current refresh-token session.

Methods
POST
Permissions
IsAuthenticated
Request serializer
LogoutSerializer
Service usage
services.auth.logout_user
Response
empty body on success
Main status codes
205 Reset Content
400 Bad Request for invalid refresh token

This is the single-session logout endpoint.

LogoutAllView¶

Revokes all active sessions for the authenticated user.

Methods
POST
Permissions
IsAuthenticated
Service usage
services.auth.logout_all_user_sessions
Response
detail message
Main status codes
200 OK

This is used for “log out everywhere” behavior.

MyDevicesView¶

Lists devices registered for the authenticated user.

Methods
GET
Permissions
IsAuthenticated
Serializer
DeviceSerializer
Service usage
services.auth.list_user_devices
Response
list of devices with active session summaries
Main status codes
200 OK

This is intended for account/device management screens.

RevokeSessionView¶

Revokes a specific owned session.

Methods
POST
Permissions
IsAuthenticated
Service usage
services.auth.revoke_user_session
URL parameters
session_id
Response
detail message
Main status codes
200 OK
404 Not Found if the session is not owned by the user or does not exist

This allows selective session revocation.

ChangePasswordView¶

Changes the authenticated user’s password.

Methods
POST
Permissions
IsAuthenticated
Request serializer
ChangePasswordSerializer
Service usage
services.auth.change_user_password
Extra behavior
refreshes Django session auth hash via update_session_auth_hash
Main status codes
200 OK
400 Bad Request on serializer validation failure

This endpoint is for authenticated password changes.

ForgotPasswordView¶

Initiates the password reset flow.

Methods
POST
Permissions
AllowAny
Throttling
AnonRateThrottle
ScopedRateThrottle
scope: password_reset
Request serializer
ForgotPasswordSerializer
Service usage
services.auth.issue_password_reset
Response
generic success message
Main status codes
200 OK

This endpoint intentionally returns the same success response whether or not the email exists.

ResetPasswordView¶

Completes a password reset using reset token payload.

Methods
POST
Permissions
AllowAny
Throttling
AnonRateThrottle
ScopedRateThrottle
scope: password_reset_confirm
Request serializer
ResetPasswordSerializer
Service usage
services.auth.reset_user_password
Main status codes
200 OK
400 Bad Request on invalid token or payload

This is the final step of the password reset flow.

`views.devices`¶

UpsertDeviceView¶

Registers or updates the current device for the authenticated user.

Methods
POST
Permissions
IsAuthenticated
Request serializer
DeviceUpsertSerializer
Response serializer
DeviceSerializer
Behavior
upserts the device by (user, device_id)
updates device metadata and last seen timestamp
Main status codes
200 OK

This endpoint is useful for device refresh, push token update, and mobile re-registration.

`views.me`¶

MeView¶

Returns the current authenticated user payload.

Methods
GET
Permissions
IsAuthenticated
Response serializer
MeSerializer
Main status codes
200 OK

This is the main “current user” endpoint.

UpdateProfileView¶

Updates the authenticated user’s workforce profile.

Methods
PATCH
Permissions
IsAuthenticated
Request/response serializer
UserProfileSerializer
Main status codes
200 OK
400 Bad Request on validation failure

This endpoint is used for self-service profile editing.

UpdateSettingsView¶

Updates frontend/user settings for the authenticated user.

Methods
PATCH
Permissions
IsAuthenticated
Request/response serializer
UserSettingsSerializer
Main status codes
200 OK
400 Bad Request

This endpoint updates user-specific UI and preferences.

MeNotificationPreferencesView¶

Reads and updates effective notification preferences.

Methods
GET
PATCH
Permissions
IsAuthenticated
Request serializer for patch
NotificationPrefsPatchSerializer
Behavior
computes defaults from notification registry
overlays user overrides from settings JSON
returns stable version hash
Main status codes
200 OK

This endpoint provides a normalized notification preference contract for the frontend.

MeWorkScheduleView¶

Reads and updates the authenticated user’s work schedule.

Methods
GET
PATCH
Permissions
IsAuthenticated
Serializer
UserWorkScheduleSerializer
Behavior
ensures schedule exists
ensures stable 0..6 day rows exist
Main status codes
200 OK
400 Bad Request on schedule validation failure

This endpoint gives the frontend a stable weekly scheduling structure.

`views.bootstrap`¶

BootstrapView¶

Returns a combined bootstrap payload used after login/app load.

Methods
GET
Permissions
IsAuthenticated
Response content
me
user organizations
user teams
Serializer usage
MeSerializer
organization serializer from orgs
team serializer from teams
Main status codes
200 OK

This endpoint reduces frontend startup round trips.

`views.invites`¶

InviteListCreateView¶

Lists invites for an org or creates a new invite.

Methods
GET
POST
Permissions
IsAuthenticated
Request serializers
CreateInviteSerializer for POST
Response serializers
InviteListSerializer for GET
InviteSerializer for POST
Service usage
services.invite.list_invites_for_org
services.invite.create_invite
services.invite.can_invite_to_org
Query/body inputs
org_id
optional status filter for listing
Main status codes
200 OK
201 Created
400 Bad Request
403 Forbidden
404 Not Found

This is the main invite management endpoint for org admins.

InvitePreviewView¶

Returns public preview information for an invite token.

Methods
GET
Permissions
AllowAny
Response serializer
InvitePreviewModelSerializer
URL parameters
token
Main status codes
200 OK
404 Not Found

This endpoint is safe for invite landing pages because it returns masked email data rather than the full email.

ResendInviteView¶

Resends an invite.

Methods
POST
Permissions
IsAuthenticated
Response serializer
InviteSerializer
Service usage
services.invite.resend_invite
services.invite.can_invite_to_org
URL parameters
invite_id
Query/body inputs
org_id
Main status codes
200 OK
400 Bad Request
403 Forbidden
404 Not Found

This endpoint supports invite follow-up without creating a duplicate invite.

CancelInviteView¶

Cancels a pending invite.

Methods
POST
Permissions
IsAuthenticated
Response serializer
InviteSerializer
Service usage
services.invite.cancel_invite
services.invite.can_invite_to_org
URL parameters
invite_id
Query/body inputs
org_id
Main status codes
200 OK
400 Bad Request
403 Forbidden
404 Not Found

This endpoint marks an invite unusable while preserving history.

AcceptInviteView¶

Accepts an invite and creates the correct membership.

Methods
POST
Permissions
AllowAny
Request serializer
AcceptInviteSerializer
Service usage
services.invite.accept_invite
Main status codes
200 OK
400 Bad Request
403 Forbidden
404 Not Found

This endpoint supports: - authenticated matching-user acceptance - anonymous acceptance with account creation - existing-account reuse by email

`views.skills`¶

SkillViewSet¶

CRUD-style viewset for the skill directory.

Actions
list
retrieve
create
partial_update
destroy
Permissions
IsAuthenticated
HasCurrentOrg
IsInternalUser
Serializers
read: SkillOutSerializer
write: SkillWriteSerializer
Filtering
search on name, category
ordering on category, name, id
optional include_inactive
Extra authorization
write actions require org admin/superuser in current org
Main status codes
200 OK
201 Created
403 Forbidden

This endpoint manages the global skill directory exposed to internal users.

UserSkillsViewSet¶

Bulk/list operations for one user’s skill assignments.

Actions
list
replace
Permissions
IsAuthenticated
HasCurrentOrg
IsInternalUser
Serializers
read: UserSkillOutSerializer
write: UserSkillsReplaceSerializer
URL parameters
user_id
Extra authorization
self-edit allowed
superuser allowed
same-org management rules enforced
Main status codes
200 OK
403 Forbidden
404 Not Found

This endpoint is used for replacing a user’s full skill set.

UserSkillViewSet¶

Patch/delete operations for a single UserSkill row.

Actions
partial_update
destroy
Permissions
IsAuthenticated
HasCurrentOrg
IsInternalUser
Serializer
UserSkillPatchSerializer
URL parameters
pk
Extra authorization
self-edit allowed
same-org management rules enforced
Main status codes
200 OK
204 No Content
403 Forbidden
404 Not Found

This endpoint supports incremental updates to one assigned skill row.

View relationship overview¶

flowchart TD
    LoginView --> LoginSerializer
    LoginView --> AuthService["services.auth.login_user"]

    LogoutView --> LogoutSerializer
    LogoutView --> AuthLogout["services.auth.logout_user"]

    LogoutAllView --> AuthLogoutAll["services.auth.logout_all_user_sessions"]
    MyDevicesView --> DeviceSerializer
    MyDevicesView --> AuthDevices["services.auth.list_user_devices"]
    RevokeSessionView --> AuthRevoke["services.auth.revoke_user_session"]

    ChangePasswordView --> ChangePasswordSerializer
    ChangePasswordView --> AuthChangePw["services.auth.change_user_password"]

    ForgotPasswordView --> ForgotPasswordSerializer
    ForgotPasswordView --> AuthForgot["services.auth.issue_password_reset"]

    ResetPasswordView --> ResetPasswordSerializer
    ResetPasswordView --> AuthReset["services.auth.reset_user_password"]

    UpsertDeviceView --> DeviceUpsertSerializer
    UpsertDeviceView --> DeviceSerializer

    MeView --> MeSerializer
    UpdateProfileView --> UserProfileSerializer
    UpdateSettingsView --> UserSettingsSerializer
    MeNotificationPreferencesView --> NotificationPrefsPatchSerializer
    MeWorkScheduleView --> UserWorkScheduleSerializer

    InviteListCreateView --> CreateInviteSerializer
    InviteListCreateView --> InviteListSerializer
    InviteListCreateView --> InviteSerializer
    InviteListCreateView --> InviteService["services.invite"]

    InvitePreviewView --> InvitePreviewModelSerializer
    ResendInviteView --> InviteSerializer
    ResendInviteView --> InviteService
    CancelInviteView --> InviteSerializer
    CancelInviteView --> InviteService
    AcceptInviteView --> AcceptInviteSerializer
    AcceptInviteView --> InviteService

    SkillViewSet --> SkillOutSerializer
    SkillViewSet --> SkillWriteSerializer
    UserSkillsViewSet --> UserSkillsReplaceSerializer
    UserSkillsViewSet --> UserSkillOutSerializer
    UserSkillViewSet --> UserSkillPatchSerializer

¶

Endpoint interaction overview¶

sequenceDiagram
    participant Client
    participant View
    participant Serializer
    participant Service
    participant Model

    Client->>View: HTTP request
    View->>Serializer: validate input
    Serializer-->>View: validated_data
    View->>Service: execute workflow (if applicable)
    Service->>Model: query/update state
    Model-->>Service: domain objects
    Service-->>View: result
    View-->>Client: HTTP response

For simpler read endpoints, the service step may be omitted and the view may query/serialize directly.