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": "[email protected]",
      "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": "[email protected]",
  "password": "SecurePassword123!",
  "first_name": "Jane",
  "last_name": "Smith"
}

Response:

{
  "id": 2,
  "uuid": "650e8400-e29b-41d4-a716-446655440001",
  "username": "jane.smith",
  "email": "[email protected]",
  "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": "[email protected]",
  "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": "[email protected]"
}

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"]
    }
  ]
}

User-Site Relationship Management

Taruvi provides bidirectional APIs to manage user-site relationships using django-guardian permissions. These APIs allow you to:

User → Sites: Manage which sites a user can access
Site → Users: Manage which users have access to a site

Bidirectional Access

You can manage the same relationships from either direction:

/api/cloud/users/{username}/sites/ - Manage sites for a specific user
/api/cloud/sites/{site_slug}/users/ - Manage users for a specific site

User → Sites API

Manage site assignments for a specific user.

List User's Sites

Get all sites a user has access to with their permissions:

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

Query Parameters:

search: Search by site name (case-insensitive)
name: Filter by exact site name
name__contains: Filter by name containing string

Example:

GET /api/cloud/users/john.doe/sites/?search=production

Response:

{
  "success": true,
  "data": [
    {
      "slug": "production-site",
      "name": "Production Site",
      "permissions": ["view_site", "access_site"]
    },
    {
      "slug": "staging-site",
      "name": "Staging Site",
      "permissions": ["view_site"]
    }
  ],
  "total": 2,
  "message": "User sites retrieved successfully"
}

Add Sites to User

Add multiple sites to a user (non-destructive, preserves existing assignments):

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

{
  "sites": [
    {
      "slug": "site-1",
      "permissions": ["view_site", "access_site"]
    },
    {
      "slug": "site-2"
    }
  ]
}

Default Permissions

If permissions are not specified, view_site is assigned by default.

Valid Permissions:

view_site - View site information
access_site - Access site resources
manage_site - Manage site settings
manage_site_users - Manage site user permissions
admin_site - Full site administration

Response:

{
  "success": true,
  "data": {
    "assigned_sites": 2
  },
  "message": "Successfully assigned 2 site(s) to user"
}

Replace All Sites for User

Replace all site assignments (atomic operation):

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

{
  "sites": [
    {
      "slug": "site-1",
      "permissions": ["view_site"]
    }
  ]
}

Destructive Operation

PUT replaces ALL existing site assignments. Use an empty array to remove all site permissions.

Response:

{
  "success": true,
  "data": {
    "total_sites": 1
  },
  "message": "Successfully replaced site assignments (1 sites)"
}

Remove Sites from User

Remove multiple sites from a user (batch operation):

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

{
  "sites": ["site-1", "site-2", "site-3"]
}

Response:

{
  "success": true,
  "message": "Removed 3 site(s) from user (6 permissions deleted)"
}

Site → Users API

Manage user assignments for a specific site.

List Site's Users

Get all users with access to a site:

GET /api/cloud/sites/{site_slug}/users/
Authorization: Bearer YOUR_ACCESS_TOKEN

Query Parameters:

search: Search by username, email, first name, or last name

Example:

GET /api/cloud/sites/production-site/users/?search=john

Response:

{
  "success": true,
  "data": [
    {
      "username": "john.doe",
      "email": "[email protected]",
      "name": "John Doe",
      "permissions": ["view_site", "access_site", "manage_site"]
    },
    {
      "username": "jane.smith",
      "email": "[email protected]",
      "name": "Jane Smith",
      "permissions": ["view_site"]
    }
  ],
  "total": 2,
  "message": "Site users retrieved successfully"
}

Add Users to Site

Add multiple users to a site (non-destructive):

POST /api/cloud/sites/{site_slug}/users/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "users": [
    {
      "username": "john.doe",
      "permissions": ["view_site", "access_site"]
    },
    {
      "username": "jane.smith"
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "assigned_users": 2
  },
  "message": "Successfully assigned 2 user(s) to site"
}

Replace All Users for Site

Replace all user assignments (atomic operation):

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

{
  "users": [
    {
      "username": "john.doe",
      "permissions": ["admin_site"]
    }
  ]
}

Remove Users from Site

Remove multiple users from a site:

DELETE /api/cloud/sites/{site_slug}/users/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "users": ["john.doe", "jane.smith"]
}

Response:

{
  "success": true,
  "message": "Removed 2 user(s) from site (4 permissions deleted)"
}

Permission Model

Who can manage user-site relationships:

Superusers: Can manage any user's site assignments
Organization Admins/Owners: Can manage user-site relationships within their organization
Users with manage_organization permission: Can manage relationships within their organization
Self-view: Users can view (but not modify) their own site assignments

Validation Rules:

Sites must belong to the same organization as the user
Users must be members of the organization that owns the site
Self-modification is not allowed (users cannot modify their own site assignments)
Cross-organization assignments are denied

Use Cases

Onboarding a New Team Member:

# Add user to organization first
POST /api/cloud/organizations/acme-corp/members/
{
  "user_id": "john.doe"
}

# Then assign site access
POST /api/cloud/users/john.doe/sites/
{
  "sites": [
    {"slug": "production", "permissions": ["view_site"]},
    {"slug": "staging", "permissions": ["view_site", "access_site"]}
  ]
}

Bulk User Assignment to New Site:

POST /api/cloud/sites/new-project/users/
{
  "users": [
    {"username": "john.doe", "permissions": ["admin_site"]},
    {"username": "jane.smith", "permissions": ["view_site", "access_site"]},
    {"username": "bob.johnson", "permissions": ["view_site"]}
  ]
}

Role Change (Promotion to Site Admin):

# Replace existing permissions with admin
PUT /api/cloud/users/john.doe/sites/
{
  "sites": [
    {"slug": "production", "permissions": ["admin_site"]}
  ]
}

Offboarding User:

# Remove all site access
DELETE /api/cloud/users/john.doe/sites/
{
  "sites": ["production", "staging", "development"]
}

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": "[email protected]"
  }
}

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​

User-Site Relationship Management​

User → Sites API​

List User's Sites​

Add Sites to User​

Replace All Sites for User​

Remove Sites from User​

Site → Users API​

List Site's Users​

Add Users to Site​

Replace All Users for Site​

Remove Users from Site​

Permission Model​

Use Cases​

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

User-Site Relationship Management

User → Sites API

List User's Sites

Add Sites to User

Replace All Sites for User

Remove Sites from User

Site → Users API

List Site's Users

Add Users to Site

Replace All Users for Site

Remove Users from Site

Permission Model

Use Cases

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