Users

Users are the core authentication and authorization entities in Taruvi Cloud. Each user can belong to multiple organizations and have access to multiple sites with different permission levels.

Username-Based URLs

All user endpoints use username-based URLs (e.g., /api/cloud/users/john.doe/) for accessing and managing user resources. UUIDs are still supported for identification purposes.

Overview

A user represents an individual account in Taruvi Cloud. Users can:

Authenticate: Login via JWT, session, or OAuth
Multi-Organization: Belong to multiple organizations
Multi-Tenant: Access multiple sites with different permissions
Role-Based: Have different roles and permissions per organization/site
Profile Management: Manage personal information and settings

Key Features

Authentication

Taruvi supports multiple authentication methods:

JWT Tokens: Stateless authentication for APIs
Session Auth: Cookie-based for browsable API
OAuth/Social: Google, GitHub, and other providers

Multi-Organization Membership

Users can be members of multiple organizations:

Different roles per organization
Independent permissions per organization
Cross-organization collaboration

Site Access

Users can access multiple sites within organizations:

Site-specific permissions
Tenant-aware operations
Isolated data access per site

Soft Delete

Users are soft-deleted for audit trail:

is_active: Controls login access
is_deleted: Marks as deleted but preserves data
Restoration capability

User Model

Fields

Field	Type	Description
`id`	integer	Primary key
`uuid`	UUID	Unique identifier (read-only)
`username`	string	Unique username (required, used in URLs)
`email`	string	Email address (required, unique)
`first_name`	string	First name (optional)
`last_name`	string	Last name (optional)
`is_active`	boolean	User can login
`is_staff`	boolean	Admin access
`is_superuser`	boolean	Full permissions
`is_deleted`	boolean	Soft delete flag
`date_joined`	datetime	Account creation date (read-only)
`last_login`	datetime	Last login timestamp (read-only)

Using Users

Listing Users

Get all users:

GET /api/cloud/users/
Authorization: Bearer YOUR_ACCESS_TOKEN

Query Parameters:

search: Search by username, email, name
is_active: Filter by active status (true, false, or all)
is_staff: Filter by staff status
organization_slug: Filter by organization membership
organization_uuid: Filter by organization UUID (alternative to slug)
ordering: Sort results (e.g., username, -date_joined)

Organization Context & Visibility Rules

When filtering by organization, visibility depends on your role:

Organization Admin/Owner: See all members in the organization
User with manage_organization permission: See all members
Regular member: See only yourself
No organization filter + view_user permission: See all users
No organization filter + no permission: See only yourself

Example:

GET /api/cloud/users/?organization_slug=acme-corp&is_active=true

Response:

{
  "count": 25,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "username": "john.doe",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "is_active": true,
      "is_staff": false,
      "is_superuser": false,
      "is_deleted": false,
      "date_joined": "2024-01-15T10:30:00Z"
    }
  ]
}

Creating a User

Create a new user account:

POST /api/cloud/users/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "username": "jane.smith",
  "email": "jane@example.com",
  "password": "SecurePassword123!",
  "first_name": "Jane",
  "last_name": "Smith"
}

Response:

{
  "id": 2,
  "uuid": "650e8400-e29b-41d4-a716-446655440001",
  "username": "jane.smith",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "is_active": true,
  "is_deleted": false,
  "date_joined": "2024-01-20T14:20:00Z"
}

Retrieving User Details

Get details of a specific user:

GET /api/cloud/users/{username}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/cloud/users/john.doe/

Response:

{
  "id": 1,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "username": "john.doe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "is_active": true,
  "is_staff": false,
  "is_superuser": false,
  "is_deleted": false,
  "date_joined": "2024-01-15T10:30:00Z",
  "organizations": [
    {
      "slug": "acme-corp",
      "name": "Acme Corporation",
      "role": "member"
    }
  ]
}

Updating a User

Update user information:

PUT /api/cloud/users/{username}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com"
}

Example:

PUT /api/cloud/users/john.doe/
{
  "first_name": "John",
  "last_name": "Smith"
}

Partial update:

PATCH /api/cloud/users/{username}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "first_name": "Johnny"
}

Deleting a User (Soft Delete)

Soft delete a user:

DELETE /api/cloud/users/{username}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

DELETE /api/cloud/users/john.doe/

Soft Delete Behavior

User deletion is a soft delete operation:

Sets is_deleted=true and is_active=false
User data is preserved for audit trail
User cannot login after deletion
All organization memberships are removed (hard deleted)
Users cannot delete themselves
Non-superusers cannot delete superusers

Deactivating a User

Deactivate without deleting:

PATCH /api/cloud/users/{username}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "is_active": false
}

Organization Membership

Adding User to Organization

POST /api/cloud/organizations/{org_slug}/members/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "user_id": "john.doe"
}

Example:

POST /api/cloud/organizations/acme-corp/members/
{
  "user_id": "john.doe"
}

Listing Organization Members

GET /api/cloud/organizations/{org_slug}/members/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/cloud/organizations/acme-corp/members/

Removing User from Organization

DELETE /api/cloud/organizations/{org_slug}/members/{username}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

DELETE /api/cloud/organizations/acme-corp/members/john.doe/

Site Permissions

Users can have specific permissions for sites within organizations:

POST /api/cloud/organizations/{org_slug}/members/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "user_id": "john.doe",
  "sites": [
    {
      "slug": "production-site",
      "permissions": ["view_site", "manage_site"]
    },
    {
      "slug": "staging-site",
      "permissions": ["view_site"]
    }
  ]
}

Groups

Users can be assigned to groups for shared permissions:

Platform-Level Groups

# Get user with groups
GET /api/cloud/users/john.doe/

# Response includes groups
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "username": "john.doe",
  "groups": [
    {
      "id": 1,
      "name": "Developers"
    }
  ]
}

Organization-Level Groups

Assign users to organization-specific groups:

POST /api/cloud/organizations/acme-corp/members/
{
  "user_id": "john.doe",
  "group_ids": [1, 2]
}

Authentication

JWT Authentication

Get access token:

POST /api/cloud/auth/jwt/token/
Content-Type: application/json

{
  "username": "john.doe",
  "password": "your-password"
}

Response:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "user": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "username": "john.doe",
    "email": "john@example.com"
  }
}

Use in requests:

GET /api/cloud/users/john.doe/
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Refresh Token

POST /api/cloud/auth/jwt/token/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Verify Token

POST /api/cloud/auth/jwt/token/verify/
Content-Type: application/json

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Logout (Blacklist Token)

POST /api/cloud/auth/jwt/token/blacklist/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

OAuth/Social Authentication

Taruvi supports OAuth authentication with various providers:

Google OAuth
GitHub OAuth
Other social providers

See Social Authentication Documentation for setup and usage.

Permissions

User-level permissions:

Permission	Description
`view_user`	View user details
`add_user`	Create new users
`change_user`	Update user information
`delete_user`	Delete users

Users also inherit permissions from:

Organization membership
Group assignments
Site-specific permissions

Best Practices

Unique Usernames: Ensure usernames are unique and descriptive
Strong Passwords: Enforce strong password policies
Email Verification: Verify email addresses during signup
Soft Deletes: Deactivate users instead of hard deleting
Least Privilege: Grant minimum required permissions
Regular Audits: Review user access and permissions regularly
MFA: Implement multi-factor authentication for sensitive accounts
Session Management: Set appropriate token expiration times

Security Considerations

Password Storage: Passwords are hashed using Django's default hasher (PBKDF2)
Token Expiration: JWT tokens have configurable expiration
Rate Limiting: Login attempts are rate-limited
Permission Checks: All operations check object-level permissions
Audit Trail: User actions are logged for compliance

Common Workflows

User Registration Flow

User submits registration form
Create user account (inactive by default)
Send verification email
User clicks verification link
Activate user account
User can login

Organization Onboarding

Create organization
Send invitation to users
Users accept invitation
Assign users to groups
Grant site-specific permissions
Users can access organization resources

Password Reset

User requests password reset
System sends reset email
User clicks reset link
User sets new password
Previous tokens are invalidated

Error Responses

User Not Found

{
  "detail": "Not found.",
  "code": "not_found",
  "status_code": 404
}

Duplicate Username

{
  "username": ["A user with that username already exists."],
  "code": "unique_constraint",
  "status_code": 400
}

Permission Denied

{
  "detail": "You do not have permission to perform this action.",
  "code": "permission_denied",
  "status_code": 403
}

Invalid Credentials

{
  "detail": "No active account found with the given credentials",
  "code": "invalid_credentials",
  "status_code": 401
}

User Management API - Complete API reference for user operations
Organizations - Manage user organization memberships
Groups - Organize users with group-based permissions
Permissions - Fine-grained access control
Social Authentication - OAuth and social login setup
Cloud Console API - Complete Cloud Console overview

Overview​

Key Features​

Authentication​

Multi-Organization Membership​

Site Access​

Soft Delete​

User Model​

Fields​

Using Users​

Listing Users​

Creating a User​

Retrieving User Details​

Updating a User​

Deleting a User (Soft Delete)​

Deactivating a User​

Organization Membership​

Adding User to Organization​

Listing Organization Members​

Removing User from Organization​

Site Permissions​

Groups​

Platform-Level Groups​

Organization-Level Groups​

Authentication​

JWT Authentication​

Refresh Token​

Verify Token​

Logout (Blacklist Token)​

OAuth/Social Authentication​

Permissions​

Best Practices​

Security Considerations​

Common Workflows​

User Registration Flow​

Organization Onboarding​

Password Reset​

Error Responses​

User Not Found​

Duplicate Username​

Permission Denied​

Invalid Credentials​

Related Features​

Overview

Key Features

Authentication

Multi-Organization Membership

Site Access

Soft Delete

User Model

Fields

Using Users

Listing Users

Creating a User

Retrieving User Details

Updating a User

Deleting a User (Soft Delete)

Deactivating a User

Organization Membership

Adding User to Organization

Listing Organization Members

Removing User from Organization

Site Permissions

Groups

Platform-Level Groups

Organization-Level Groups

Authentication

JWT Authentication

Refresh Token

Verify Token

Logout (Blacklist Token)

OAuth/Social Authentication

Permissions

Best Practices

Security Considerations

Common Workflows

User Registration Flow

Organization Onboarding

Password Reset

Error Responses

User Not Found

Duplicate Username

Permission Denied

Invalid Credentials

Related Features