63 lines
3.7 KiB
Markdown
63 lines
3.7 KiB
Markdown
# Authentication Endpoints
|
|
|
|
## Purpose
|
|
Detail authentication-related endpoints for registration, login, password change, token refresh, and auth-adjacent resources (users/accounts/plans/sites/sectors/industries/seed keywords).
|
|
|
|
## Code Locations (exact paths)
|
|
- Routing: `backend/igny8_core/auth/urls.py`
|
|
- Views: `backend/igny8_core/auth/views.py`
|
|
- Serializers: `backend/igny8_core/auth/serializers.py`
|
|
- Auth utils: `backend/igny8_core/auth/utils.py`
|
|
|
|
## High-Level Responsibilities
|
|
- Issue JWT access/refresh tokens and session auth on login.
|
|
- Register users, change passwords, refresh tokens.
|
|
- Provide CRUD for users, accounts, subscriptions, site access, plans, sites, sectors, industries, seed keywords via routers.
|
|
|
|
## Detailed Behavior
|
|
- APIViews:
|
|
- `POST /api/v1/auth/register/` → `RegisterView`: validates via `RegisterSerializer`, creates user, returns user data.
|
|
- `POST /api/v1/auth/login/` → `LoginView`: validates credentials, logs in user (session), generates access/refresh JWTs with expiries, returns user data and tokens; 401 on invalid credentials.
|
|
- `POST /api/v1/auth/change-password/` → `ChangePasswordView`: requires auth, validates old/new passwords, updates password; 400 on invalid current password or validation errors.
|
|
- `POST /api/v1/auth/refresh/` → `RefreshTokenView`: accepts refresh token, validates, issues new access token with expiry; 401/400 on invalid/expired tokens.
|
|
- Routers under `/api/v1/auth/`:
|
|
- `groups/`, `users/`, `accounts/`, `subscriptions/`, `site-access/`, `plans/`, `sites/`, `sectors/`, `industries/`, `seed-keywords/` mapped to corresponding viewsets in `auth/views.py`. These use base viewsets with tenant filtering and role checks (see module docs).
|
|
- CSV admin helpers (admin UI, not public API): CSV import/export for industry/industrysector/seedkeyword under `/admin/igny8_core_auth/...`.
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- `User`, `Account`, `Plan`, `Site`, `Sector`, `Industry`, `SeedKeyword`, `Subscription`, `SiteUserAccess`, `Group`.
|
|
|
|
## Execution Flow
|
|
- APIView endpoints use serializers to validate, then issue tokens via auth utils (JWT encode with user_id/account_id, type, exp).
|
|
- Router endpoints inherit base viewsets; AccountContextMiddleware sets `request.account`; JWT/Session auth applied per settings; permissions enforced per viewset.
|
|
|
|
## Cross-Module Interactions
|
|
- Tokens issued here are required by planner/writer/billing/automation/etc.
|
|
- Account/plan/site data informs tenancy and plan enforcement in middleware and billing limits.
|
|
|
|
## State Transitions
|
|
- User creation, password changes, session login, token issuance/refresh.
|
|
- CRUD on accounts/sites/sectors/industries/seed keywords via routers.
|
|
|
|
## Error Handling
|
|
- Unified error responses via helpers; login returns 401 on invalid credentials; refresh returns 401/400 on invalid/expired tokens; validation errors return 400 with field errors.
|
|
|
|
## Tenancy Rules
|
|
- Login loads user with account+plan; middleware later enforces active plan. Router viewsets inherit account/site/sector filtering where applicable.
|
|
|
|
## Billing Rules
|
|
- None directly; plan data carried on Account; credits handled elsewhere.
|
|
|
|
## Background Tasks / Schedulers
|
|
- None.
|
|
|
|
## Key Design Considerations
|
|
- JWT payload includes user_id, account_id, type, exp/iat; uses `JWT_SECRET_KEY`/`JWT_ALGORITHM` from settings.
|
|
- Session login occurs alongside JWT issuance to support browser-based flows.
|
|
|
|
## How Developers Should Work With This Module
|
|
- Use provided APIViews for auth; do not handcraft JWTs—use `generate_access_token`/`generate_refresh_token`.
|
|
- When extending auth resources (e.g., new user fields), update serializers and viewsets; keep router paths stable.
|
|
- Maintain unified responses and permission/tenancy checks in viewsets.
|
|
|