# 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.