Skip to main content
Organizations in QFieldCloud allow teams to collaborate on projects with centralized management, shared resources, and role-based access control.

​
Overview

An organization is a collaborative workspace that:
  • Groups multiple members under a single entity
  • Owns and manages projects collectively
  • Provides subscription-based features and storage
  • Enables team-based project collaboration
  • Allows granular permission control through roles

​
Organization Structure

​
Organization Owner

Every organization has a single owner who:
  • Created or was assigned ownership of the organization
  • Has full administrative control
  • Cannot be removed as a member (they own the organization)
  • Can transfer ownership to another member
  • Manages subscription and billing

​
Organization Members

Members are individual users added to the organization with specific roles:
  • Admin: Full management permissions (except billing)
  • Member: Standard access to organization projects based on project-level permissions
See Roles & Permissions for detailed role capabilities.

​
Teams

Organizations can create teams to group members for easier project collaboration. Teams:
  • Are formatted as @<organization_name>/<team_name>
  • Can be added as collaborators to projects
  • Inherit permissions from the organization
  • Members must be organization members first

​
Creating an Organization

​
Prerequisites

  • A registered QFieldCloud account
  • Available trial organizations (for trial plans) or an active subscription

​
Via Web Interface

  1. Navigate to your account settings
  2. Click on “Organizations”
  3. Click “Create Organization”
  4. Enter organization details:
    • Username: Unique identifier (3-150 characters, letters, numbers, underscores, hyphens)
    • Email: Organization contact email
    • Display name: Human-readable name
  5. Select a subscription plan
  6. Complete the creation process

​
Via API

curl -X POST https://app.qfield.cloud/api/v1/organizations/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my_org",
    "email": "[email protected]",
    "first_name": "",
    "last_name": ""
  }'
The username field must:
  • Be between 3 and 150 characters
  • Contain only letters, numbers, underscores, or hyphens
  • Begin with a letter
  • Be unique across all QFieldCloud users and organizations

​
Organization Settings

​
Profile Information

Update organization profile details:
  • Username (must remain unique)
  • Email address
  • Avatar/logo
  • Bio and description
  • Location
  • Company information
  • Social media links (e.g., Twitter)

​
Subscription Management

Organization owners can manage:
  • Active Plan: Current subscription tier
  • Storage: Total storage allocation and usage
  • Additional Packages: Extra storage or resources
  • Billing Cycle: Monthly or annual billing
  • Payment Methods: Manage payment information

​
Storage Limits

Organizations have storage quotas based on their plan: 
# Example: Check organization storage
from qfieldcloud.core.models import Organization

org = Organization.objects.get(username='my_org')
account = org.useraccount

# Total storage from plan + packages
total_storage = account.current_subscription.active_storage_total_bytes

# Currently used storage
used_storage = account.storage_used_bytes

# Available storage
free_storage = account.storage_free_bytes

# Usage ratio (0.0 to 1.0)
usage_ratio = account.storage_used_ratio

​
Member Limits

Organization plans may restrict the number of members:
  • max_organization_members: Maximum members allowed (-1 = unlimited)
  • Existing members beyond the limit remain active if plan changes
  • New members cannot be added when at capacity
Attempting to add members beyond the plan limit will raise a ReachedMaxOrganizationMembersError.

​
Subscription Plans

​
Plan Types

Organizations can subscribe to different plan tiers:
  • Default Plan: Free tier with basic features
  • Trial Plan: Limited-time evaluation with premium features
  • Premium Plans: Enhanced storage, features, and support

​
Plan Features

Plan configuration determines:
FeatureDescription
storage_mbBase storage allocation in megabytes
storage_keep_versionsNumber of file versions to retain
job_minutesProcessing time allocation
can_add_storageAllow purchasing additional storage
is_external_db_supportedSupport for external databases (PostGIS, etc.)
max_organization_membersMember limit (-1 = unlimited)
max_premium_collaborators_per_private_projectCollaborator limit per private project
is_premiumPremium plan status (affects support access)

​
Trial Organizations

Users can create a limited number of trial organizations: 
# Check remaining trial organizations
from qfieldcloud.core.models import Person

user = Person.objects.get(username='username')
remaining_trials = user.remaining_trial_organizations
  • Trial duration is configured via TRIAL_PERIOD_DAYS
  • After trial expires, organization reverts to default plan
  • Trial counter decrements when a trial organization is created

​
Transferring Ownership

Ownership can be transferred to another organization member:
1

Ensure target user is a member

The new owner must already be an organization member or admin.
2

Update the organization owner

Change the organization_owner field to the new owner.
3

Automatic role adjustment

The system automatically:
  • Removes the new owner from the members list (they’re now the owner)
  • Adds the previous owner as an admin member
# Example: Transfer ownership
from qfieldcloud.core.models import Organization, Person, OrganizationMember

org = Organization.objects.get(username='my_org')
new_owner = Person.objects.get(username='new_owner')

# Transfer ownership
org.organization_owner = new_owner
org.save()

# The previous owner is now an admin member automatically

​
Deleting an Organization

Deleting an organization is permanent and will:
  • Delete all projects owned by the organization
  • Remove all members and teams
  • Cancel the active subscription
  • Delete all associated data
Only the organization owner can delete the organization.

​
API Reference

​
List Organizations

Get all organizations the authenticated user is a member of: 
GET /api/v1/organizations/

​
Get Organization Details

Retrieve specific organization information: 
GET /api/v1/users/{organization_username}/

​
Update Organization

Update organization profile (admin only): 
PATCH /api/v1/users/{organization_username}/
Content-Type: application/json

{
  "email": "[email protected]",
  "bio": "Updated organization description"
}

​
Delete Organization

Delete an organization (owner only): 
DELETE /api/v1/users/{organization_username}/

Members

Learn how to add and manage organization members

Roles & Permissions

Understand role-based access control

Build docs developers (and LLMs) love

Get started for freeTalk to us