Organization Members - QFieldCloud

Organization members are individual users who belong to an organization and can access organization-owned projects based on their assigned roles.

Overview

Membership in an organization provides:

Access to organization-owned projects
Ability to collaborate with other members
Project creation permissions (for admins)
Team membership eligibility
Role-based permissions

Member Types

Individual Members

Standard users (Person type) added to the organization:

Must have a QFieldCloud account
Can be assigned Admin or Member role
Can be added to teams
Can be project collaborators

Organization Owner

The user who owns the organization:

Not listed in the members table (they own the organization)
Has full administrative privileges
Cannot be removed (only ownership can be transferred)
Manages billing and subscriptions

Member Roles

Organization members have one of two roles:

Admin

Administrators have extensive management permissions:

Add and remove members
Create and manage teams
Create organization projects
Manage organization settings (except billing)
Assign project collaborators
Manage organization secrets

Member

Standard members have basic access:

View organization and other members
Access projects where they’re collaborators
Cannot manage organization settings
Cannot add/remove members or teams

Project-level permissions are separate from organization roles. A member can be assigned different roles on different projects.

Adding Members

Prerequisites

Organization admin or owner permissions
Target user must have a QFieldCloud account
Organization must not exceed member limit
User must not already be a member or owner

Via Web Interface

Navigate to organization settings

Go to your organization page and click “Members”.

Click 'Add Member'

Enter the username of the user to add.

Select role

Choose either “Admin” or “Member” role.

Confirm

The user is now a member of the organization.

Via API

curl -X POST https://app.qfield.cloud/api/v1/organizations/my_org/members/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member": "username",
    "role": "member"
  }'

Member Validation

When adding a member, the system validates:

Not the owner: Cannot add the organization owner as a member
Member limit: Organization hasn’t reached max_organization_members
Not duplicate: User isn’t already a member
Valid user: User exists and is a Person (not another organization)

If the organization has reached its member limit (defined by the subscription plan’s max_organization_members), attempting to add new members will fail with a ReachedMaxOrganizationMembersError.

Managing Members

Listing Members

Retrieve all members of an organization:

curl https://app.qfield.cloud/api/v1/organizations/my_org/members/ \
  -H "Authorization: Token YOUR_API_TOKEN"

Response includes:

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "member": "alice",
      "role": "admin",
      "is_public": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "member": "bob",
      "role": "member",
      "is_public": false,
      "created_at": "2024-01-20T14:22:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    }
  ]
}

Viewing Member Details

Get specific member information:

GET /api/v1/organizations/{organization}/members/{username}/

Updating Member Role

Change a member’s role (admin only):

curl -X PATCH https://app.qfield.cloud/api/v1/organizations/my_org/members/username/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Public Membership

Members can be marked as public or private:

{
  "member": "username",
  "role": "member",
  "is_public": true  // Publicly visible membership
}

Public (is_public: true): Membership is visible to all users
Private (is_public: false): Membership is visible only to organization members

Removing Members

Removal Effects

When a member is removed:

Organization membership is revoked
Team memberships are automatically removed
Project collaborator status may be affected (for org-owned projects)
Active data and projects remain (only access is revoked)

Via API

curl -X DELETE https://app.qfield.cloud/api/v1/organizations/my_org/members/username/ \
  -H "Authorization: Token YOUR_API_TOKEN"

Removing a member also removes them from all teams within the organization. This is done automatically via a database cascade.

Teams

Teams are sub-groups within an organization that simplify project collaboration.

Team Basics

Teams are a special user type (User.Type.TEAM)
Username format: @<organization_name>/<team_name>
Teams can be added as project collaborators
Team members must be organization members

Creating Teams

Create a team within an organization:

curl -X POST https://app.qfield.cloud/api/v1/organizations/my_org/teams/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "field_team"
  }'

Adding Team Members

Add organization members to a team:

curl -X POST https://app.qfield.cloud/api/v1/organizations/my_org/teams/field_team/members/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"member": "username"}'

Only organization members can be added to teams. Attempting to add a non-member will fail validation with: “Cannot add team member that is not an organization member.”

Team Member Roles

When querying team members, users have a membership_role:

Admin: Organization owner (automatically has admin rights)
Member: Added to the team explicitly

Removing Team Members

DELETE /api/v1/organizations/{organization}/teams/{teamname}/members/{username}/

Deleting Teams

Remove an entire team:

DELETE /api/v1/organizations/{organization}/teams/{teamname}/

Member Query Helpers

The codebase provides helper methods to query members:

Get Organization Members

from qfieldcloud.core.models import Person, Organization

# Get all members of an organization with their roles
org = Organization.objects.get(username='my_org')
members = Person.objects.for_organization(org)

for member in members:
    print(f"{member.username}: {member.organization_role}")
    print(f"  Role origin: {member.organization_role_origin}")
    print(f"  Public: {member.organization_role_is_public}")

Get Team Members

from qfieldcloud.core.models import Person, Team

# Get all members of a team
team = Team.objects.get(username='@my_org/field_team')
members = Person.objects.for_team(team)

for member in members:
    print(f"{member.username}: {member.membership_role}")

Check Membership

from qfieldcloud.core.models import Person, Organization, OrganizationMember
from qfieldcloud.core.permissions_utils import user_has_organization_roles

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

# Check if user is an admin
is_admin = user_has_organization_roles(
    user,
    org,
    [OrganizationMember.Roles.ADMIN]
)

print(f"Is admin: {is_admin}")

Best Practices

Use teams for project groups

Instead of adding individual members to multiple projects, create teams and add the team as a collaborator. This simplifies management when team composition changes.

Limit admin roles

Grant admin roles only to users who need full management capabilities. Most users should be standard members with project-level permissions.

Monitor member limits

Track your organization’s member count against the plan limit to avoid disruption when adding new team members.

Document team purposes

Use team names and descriptions that clearly indicate their purpose (e.g., field_survey_team, data_analysts).

API Reference

Member Endpoints

Method	Endpoint	Description
GET	`/api/v1/organizations/{organization}/members/`	List all members
POST	`/api/v1/organizations/{organization}/members/`	Add a member
GET	`/api/v1/organizations/{organization}/members/{username}/`	Get member details
PATCH	`/api/v1/organizations/{organization}/members/{username}/`	Update member role
DELETE	`/api/v1/organizations/{organization}/members/{username}/`	Remove a member

Team Endpoints

Method	Endpoint	Description
GET	`/api/v1/organizations/{organization}/teams/`	List all teams
POST	`/api/v1/organizations/{organization}/teams/`	Create a team
GET	`/api/v1/organizations/{organization}/teams/{teamname}/`	Get team details
DELETE	`/api/v1/organizations/{organization}/teams/{teamname}/`	Delete a team
POST	`/api/v1/organizations/{organization}/teams/{teamname}/members/`	Add team member
DELETE	`/api/v1/organizations/{organization}/teams/{teamname}/members/{username}/`	Remove team member

Organizations

Learn about organization creation and management

Roles & Permissions

Understand permission levels for members

Get Started

Core Features

Team Management

Deployment

Development

​Overview

​Member Types

​Individual Members

​Organization Owner

​Member Roles

​Admin

​Member

​Adding Members

​Prerequisites

​Via Web Interface

​Via API

​Member Validation

​Managing Members

​Listing Members

​Viewing Member Details

​Updating Member Role

​Public Membership

​Removing Members

​Removal Effects

​Via API

​Teams

​Team Basics

​Creating Teams

​Adding Team Members

​Team Member Roles

​Removing Team Members

​Deleting Teams

​Member Query Helpers

​Get Organization Members

​Get Team Members

​Check Membership

​Best Practices

​API Reference

​Member Endpoints

​Team Endpoints

​Related Topics

Organizations

Roles & Permissions

Build docs developers (and LLMs) love

Overview

Member Types

Individual Members

Organization Owner

Member Roles

Admin

Member

Adding Members

Prerequisites

Via Web Interface

Via API

Member Validation

Managing Members

Listing Members

Viewing Member Details

Updating Member Role

Public Membership

Removing Members

Removal Effects

Via API

Teams

Team Basics

Creating Teams

Adding Team Members

Team Member Roles

Removing Team Members

Deleting Teams

Member Query Helpers

Get Organization Members

Get Team Members

Check Membership

Best Practices

API Reference

Member Endpoints

Team Endpoints

Related Topics