igny8/master-docs/20-api/ENDPOINTS/authentication.md

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.