0
# Authentication & User Management
1

2
Authentication, user management, organization management, and administrative functions for the Django CRM system. The system uses JWT authentication with organization-based multi-tenancy and role-based access control.
3

4
## Capabilities
5

6
### JWT Token Authentication
7

8
Django CRM uses JWT (JSON Web Tokens) for API authentication with access and refresh token support.
9

10
```python { .api }
11
def refresh_token(refresh_token: str) -> dict:
12
    """
13
    Refresh JWT access token using refresh token.
14

15
    Args:
16
        refresh_token (str): Valid refresh token
17

18
    Returns:
19
        dict: New access token and optional refresh token
20

21
    Example:
22
        POST /api/auth/refresh-token/
23
        {
24
            "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
25
        }
26

27
        Response:
28
        {
29
            "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
30
        }
31
    """
32
```
33

34
### Google OAuth Authentication
35

36
Google OAuth integration for seamless user authentication and account creation.
37

38
```python { .api }
39
def google_login(google_token: str) -> dict:
40
    """
41
    Authenticate user with Google OAuth token.
42

43
    Args:
44
        google_token (str): Valid Google OAuth access token
45

46
    Returns:
47
        dict: JWT access and refresh tokens with user information
48

49
    Example:
50
        POST /api/auth/google/
51
        {
52
            "token": "ya29.a0ARrdaM-google-oauth-token..."
53
        }
54

55
        Response:
56
        {
57
            "access": "jwt_access_token",
58
            "refresh": "jwt_refresh_token",
59
            "user": {
60
                "id": "user-uuid",
61
                "email": "user@example.com",
62
                "first_name": "John",
63
                "last_name": "Doe"
64
            }
65
        }
66
    """
67
```
68

69
### Dashboard and Statistics
70

71
Get dashboard overview data including counts and recent activity across all CRM entities.
72

73
```python { .api }
74
def get_dashboard() -> dict:
75
    """
76
    Get dashboard statistics and overview data.
77

78
    Returns:
79
        dict: Dashboard data with entity counts and recent items
80

81
    Headers Required:
82
        Authorization: Bearer <access_token>
83
        organization-id: <org_uuid>
84

85
    Example:
86
        GET /api/dashboard/
87

88
        Response:
89
        {
90
            "accounts": {
91
                "open_accounts": 25,
92
                "closed_accounts": 5,
93
                "accounts": [...list of recent accounts...]
94
            },
95
            "contacts": {
96
                "contacts": [...list of recent contacts...]
97
            },
98
            "leads": {
99
                "open_leads": 15,
100
                "closed_leads": 3,
101
                "leads": [...list of recent leads...]
102
            },
103
            "opportunities": {
104
                "opportunities": [...list of recent opportunities...]
105
            }
106
        }
107
    """
108
```
109

110
### User Profile Management
111

112
Manage current user's profile information and settings.
113

114
```python { .api }
115
def get_profile() -> dict:
116
    """
117
    Get current authenticated user's profile.
118

119
    Returns:
120
        dict: User profile information
121

122
    Headers Required:
123
        Authorization: Bearer <access_token>
124

125
    Example:
126
        GET /api/profile/
127

128
        Response:
129
        {
130
            "id": "user-uuid",
131
            "email": "user@example.com",
132
            "first_name": "John",
133
            "last_name": "Doe",
134
            "role": "USER",
135
            "phone": "+1234567890",
136
            "is_active": true,
137
            "org": "org-uuid",
138
            "address": {
139
                "address_line": "123 Main St",
140
                "city": "New York",
141
                "state": "NY",
142
                "postcode": "10001",
143
                "country": "USA"
144
            }
145
        }
146
    """
147
```
148

149
### User Management (Admin Only)
150

151
Administrative functions for managing users within an organization.
152

153
```python { .api }
154
def list_users(email: str = None, role: str = None, status: str = None) -> dict:
155
    """
156
    List users in organization with filtering.
157

158
    Args:
159
        email (str, optional): Filter by email
160
        role (str, optional): Filter by role ('ADMIN' or 'USER')
161
        status (str, optional): Filter by status ('Active' or 'Inactive')
162

163
    Returns:
164
        dict: Paginated list of users
165

166
    Headers Required:
167
        Authorization: Bearer <access_token> (Admin role)
168
        organization-id: <org_uuid>
169

170
    Example:
171
        GET /api/users/?role=USER&status=Active
172

173
        Response:
174
        {
175
            "count": 10,
176
            "next": null,
177
            "previous": null,
178
            "results": [
179
                {
180
                    "id": "user-uuid",
181
                    "email": "user@example.com",
182
                    "first_name": "John",
183
                    "last_name": "Doe",
184
                    "role": "USER",
185
                    "is_active": true,
186
                    "phone": "+1234567890"
187
                }
188
            ]
189
        }
190
    """
191

192
def create_user(user_data: dict) -> dict:
193
    """
194
    Create new user in organization.
195

196
    Args:
197
        user_data (dict): User information including email, name, role, phone, address
198

199
    Returns:
200
        dict: Created user information
201

202
    Headers Required:
203
        Authorization: Bearer <access_token> (Admin role)
204
        organization-id: <org_uuid>
205

206
    Example:
207
        POST /api/users/
208
        {
209
            "email": "newuser@example.com",
210
            "first_name": "Jane",
211
            "last_name": "Smith",
212
            "role": "USER",
213
            "phone": "+1987654321",
214
            "address": {
215
                "address_line": "456 Oak Ave",
216
                "city": "Boston",
217
                "state": "MA",
218
                "postcode": "02101",
219
                "country": "USA"
220
            }
221
        }
222
    """
223

224
def get_user(pk: str) -> dict:
225
    """
226
    Get detailed user information.
227

228
    Args:
229
        pk (str): User UUID
230

231
    Returns:
232
        dict: User details with associated data
233

234
    Headers Required:
235
        Authorization: Bearer <access_token>
236

237
    Example:
238
        GET /api/user/user-uuid/
239

240
        Response:
241
        {
242
            "user_obj": {...user details...},
243
            "address_obj": {...address details...},
244
            "opportunities": [...user's opportunities...],
245
            "contacts": [...user's contacts...],
246
            "cases": [...user's cases...],
247
            "comments": [...user's comments...]
248
        }
249
    """
250

251
def update_user(pk: str, user_data: dict) -> dict:
252
    """
253
    Update user information.
254

255
    Args:
256
        pk (str): User UUID
257
        user_data (dict): Updated user information
258

259
    Returns:
260
        dict: Updated user information
261

262
    Headers Required:
263
        Authorization: Bearer <access_token>
264

265
    Example:
266
        PUT /api/user/user-uuid/
267
        {
268
            "first_name": "John",
269
            "last_name": "Updated",
270
            "phone": "+1555123456"
271
        }
272
    """
273

274
def delete_user(pk: str) -> None:
275
    """
276
    Delete user (Admin only).
277

278
    Args:
279
        pk (str): User UUID
280

281
    Returns:
282
        None: 204 No Content on success
283

284
    Headers Required:
285
        Authorization: Bearer <access_token> (Admin role)
286

287
    Example:
288
        DELETE /api/user/user-uuid/
289
    """
290

291
def update_user_status(pk: str, status: str) -> dict:
292
    """
293
    Update user active/inactive status.
294

295
    Args:
296
        pk (str): User UUID
297
        status (str): 'Active' or 'Inactive'
298

299
    Returns:
300
        dict: Success message
301

302
    Headers Required:
303
        Authorization: Bearer <access_token> (Admin role)
304

305
    Example:
306
        POST /api/user/user-uuid/status/
307
        {
308
            "status": "Inactive"
309
        }
310

311
        Response:
312
        {
313
            "status": "success",
314
            "message": "User status updated successfully"
315
        }
316
    """
317
```
318

319
### Teams and Users Lookup
320

321
Get teams and users for dropdown/selection purposes across the application.
322

323
```python { .api }
324
def get_teams_and_users() -> dict:
325
    """
326
    Get teams and users for selection dropdowns.
327

328
    Returns:
329
        dict: Teams and user profiles lists
330

331
    Headers Required:
332
        Authorization: Bearer <access_token>
333
        organization-id: <org_uuid>
334

335
    Example:
336
        GET /api/users/get-teams-and-users/
337

338
        Response:
339
        {
340
            "teams": [
341
                {
342
                    "id": "team-uuid",
343
                    "name": "Sales Team",
344
                    "description": "Sales representatives"
345
                }
346
            ],
347
            "profiles": [
348
                {
349
                    "id": "user-uuid",
350
                    "user": "user-uuid",
351
                    "first_name": "John",
352
                    "last_name": "Doe"
353
                }
354
            ]
355
        }
356
    """
357
```
358

359
### Organization Management
360

361
Create and manage organizations for multi-tenant scoping.
362

363
```python { .api }
364
def list_organizations() -> list:
365
    """
366
    Get list of organizations user belongs to.
367

368
    Returns:
369
        list: User's organizations
370

371
    Headers Required:
372
        Authorization: Bearer <access_token>
373

374
    Example:
375
        GET /api/org/
376

377
        Response:
378
        [
379
            {
380
                "id": "org-uuid",
381
                "name": "ACME Corporation",
382
                "slug": "acme-corp",
383
                "billing_city": "New York",
384
                "billing_state": "NY"
385
            }
386
        ]
387
    """
388

389
def create_organization(org_data: dict) -> dict:
390
    """
391
    Create new organization.
392

393
    Args:
394
        org_data (dict): Organization information
395

396
    Returns:
397
        dict: Created organization details
398

399
    Headers Required:
400
        Authorization: Bearer <access_token>
401

402
    Example:
403
        POST /api/org/
404
        {
405
            "name": "New Company LLC"
406
        }
407

408
        Response:
409
        {
410
            "id": "new-org-uuid",
411
            "name": "New Company LLC",
412
            "slug": "new-company-llc"
413
        }
414
    """
415
```
416

417
## Authentication Headers
418

419
All authenticated endpoints require these headers:
420

421
```python { .api }
422
class AuthHeaders:
423
    """Required headers for authenticated requests"""
424
    Authorization: str  # "Bearer <access_token>"
425
    organization_id: str  # Organization UUID (for org-scoped operations)
426

427
class AdminRequiredHeaders(AuthHeaders):
428
    """Headers for admin-only endpoints - user must have ADMIN role"""
429
    pass
430
```
431

432
## User Roles
433

434
```python { .api }
435
class UserRole:
436
    """User roles in the system"""
437
    ADMIN: str = "ADMIN"  # Full administrative access
438
    USER: str = "USER"    # Standard user access
439

440
class UserStatus:
441
    """User status options"""
442
    ACTIVE: str = "Active"
443
    INACTIVE: str = "Inactive"
444
```
445

446
## Error Handling
447

448
Common authentication and authorization errors:
449

450
- **401 Unauthorized**: Invalid or expired JWT token
451
- **403 Forbidden**: User lacks required permissions (e.g., non-admin trying admin operation)
452
- **404 Not Found**: User or organization not found
453
- **400 Bad Request**: Invalid request data or missing required fields