Skip to content

Orgs — views

Responsibilities

The orgs views expose the HTTP API for:

  • organization discovery for the current user
  • current-organization detail and branding
  • internal member listing and membership management
  • customer-link visibility
  • linked customer-org member visibility

They are responsible for:

  • receiving requests and returning responses
  • enforcing authentication and current-org permissions
  • invoking serializers for payload validation
  • calling service-layer functions for organization and membership workflows
  • mapping domain/service exceptions to HTTP status codes

They are not responsible for:

  • embedding membership business rules directly
  • performing complex organization update logic in-view
  • serializer field normalization/validation logic
  • persistence-only concerns

In this app, views should remain thin orchestration layers.

Main views

views.organizations

MyOrgsView

Lists the active organizations for the authenticated user.

  • Methods
  • GET
  • Permissions
  • IsAuthenticated
  • Serializer
  • OrganizationListSerializer
  • Service usage
  • services.organization.list_user_orgs
  • Response
  • list of organizations the user belongs to, including the user’s role in each org
  • Main status codes
  • 200 OK

This endpoint is typically used by org switchers, bootstrap flows, or clients that need to know which orgs the current user can act in.

CurrentOrgDetailView

Returns the details of the current organization.

  • Methods
  • GET
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Serializer
  • OrganizationDetailSerializer
  • Service usage
  • services.organization.get_current_org
  • Response
  • full organization detail payload
  • Main status codes
  • 200 OK
  • 403 Forbidden or 400 Bad Request if current-org resolution fails upstream

This is the main read endpoint for current org settings and metadata.

CurrentOrgUpdateView

Updates the details of the current organization.

  • Methods
  • PATCH
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Request/response serializer
  • OrganizationDetailSerializer
  • Service usage
  • services.organization.get_current_org
  • services.membership.can_manage_members
  • services.organization.update_org_details
  • Response
  • updated organization payload
  • Main status codes
  • 200 OK
  • 400 Bad Request
  • 403 Forbidden

This endpoint is intended for org admins/owners managing organization settings. Permission is based on org role, not just authentication.

CurrentOrgBrandingView

Returns the branding/document identity payload for the current organization.

  • Methods
  • GET
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Serializer
  • OrganizationBrandingSerializer
  • Service usage
  • services.organization.get_current_org
  • Response
  • branding-focused organization payload including resolved branding
  • Main status codes
  • 200 OK

This endpoint is useful for settings screens, PDF branding previews, and other org-identity UI.

CurrentOrgBrandingUpdateView

Updates branding/document identity fields for the current organization.

  • Methods
  • PATCH
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Request/response serializer
  • OrganizationBrandingSerializer
  • Service usage
  • services.organization.get_current_org
  • services.membership.can_manage_members
  • services.organization.update_org_branding
  • Response
  • updated branding payload
  • Main status codes
  • 200 OK
  • 400 Bad Request
  • 403 Forbidden

This endpoint is the narrow update path for branding administration.

views.memberships

CurrentOrgMembersView

Lists active internal members of the current organization.

  • Methods
  • GET
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Serializer
  • OrgMemberListSerializer
  • Service usage
  • services.organization.get_current_org
  • services.organization.list_current_org_members
  • Response
  • list of active org members with role and basic user identity info
  • Main status codes
  • 200 OK

This endpoint is the main member directory view for the current org.

OrgMembershipRoleUpdateView

Changes the role of one org membership.

  • Methods
  • PATCH
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Request serializer
  • OrgMembershipRoleUpdateSerializer
  • Response serializer
  • OrgMembershipSerializer
  • Service usage
  • services.organization.get_current_org
  • services.membership.get_membership_by_id_for_org
  • services.membership.change_membership_role
  • URL parameters
  • membership_id
  • Main status codes
  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

This endpoint applies the org role-management rules enforced by the membership service.

OrgMembershipDeactivateView

Deactivates one org membership.

  • Methods
  • POST
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Response serializer
  • OrgMembershipSerializer
  • Service usage
  • services.organization.get_current_org
  • services.membership.get_membership_by_id_for_org
  • services.membership.deactivate_membership
  • URL parameters
  • membership_id
  • Main status codes
  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

This is the safe soft-removal endpoint for internal org members.

OrgMembershipReactivateView

Reactivates one org membership.

  • Methods
  • POST
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Response serializer
  • OrgMembershipSerializer
  • Service usage
  • services.organization.get_current_org
  • services.membership.get_membership_by_id_for_org
  • services.membership.reactivate_membership
  • URL parameters
  • membership_id
  • Main status codes
  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found

This restores an existing membership without recreating it.

views.customers

CurrentOrgCustomerLinksView

Lists customer org links for the current internal organization.

  • Methods
  • GET
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Serializer
  • CustomerLinkSerializer
  • Service usage
  • services.organization.get_current_org
  • services.membership.can_manage_members
  • Query behavior
  • lists customer links where internal_org == current org
  • Response
  • list of linked customer orgs
  • Main status codes
  • 200 OK
  • 403 Forbidden

This endpoint is currently read-only and intended for internal admins/owners.

CurrentCustomerOrgMembersView

Lists active members of a linked customer organization.

  • Methods
  • GET
  • Permissions
  • IsAuthenticated
  • HasCurrentOrg
  • Serializer
  • CustomerMembershipSerializer
  • Service usage
  • services.organization.get_current_org
  • services.membership.can_manage_members
  • URL parameters
  • customer_org_id
  • Query behavior
  • verifies an active CustomerLink exists between current internal org and target customer org
  • then returns active customer memberships
  • Main status codes
  • 200 OK
  • 403 Forbidden
  • 404 Not Found

This gives internal staff visibility into membership of linked customer organizations.

View relationship overview

flowchart TD
    OrgViews["views.organizations"]
    MembershipViews["views.memberships"]
    CustomerViews["views.customers"]

    OrgViews --> MyOrgsView["MyOrgsView"]
    OrgViews --> CurrentOrgDetailView["CurrentOrgDetailView"]
    OrgViews --> CurrentOrgUpdateView["CurrentOrgUpdateView"]
    OrgViews --> CurrentOrgBrandingView["CurrentOrgBrandingView"]
    OrgViews --> CurrentOrgBrandingUpdateView["CurrentOrgBrandingUpdateView"]

    MembershipViews --> CurrentOrgMembersView["CurrentOrgMembersView"]
    MembershipViews --> OrgMembershipRoleUpdateView["OrgMembershipRoleUpdateView"]
    MembershipViews --> OrgMembershipDeactivateView["OrgMembershipDeactivateView"]
    MembershipViews --> OrgMembershipReactivateView["OrgMembershipReactivateView"]

    CustomerViews --> CurrentOrgCustomerLinksView["CurrentOrgCustomerLinksView"]
    CustomerViews --> CurrentCustomerOrgMembersView["CurrentCustomerOrgMembersView"]

Request flow overview

sequenceDiagram
    participant Client
    participant View
    participant Serializer
    participant Service
    participant Model

    Client->>View: HTTP request
    View->>Serializer: validate input (if write action)
    Serializer-->>View: validated_data
    View->>Service: execute org/membership workflow
    Service->>Model: query/update state
    Model-->>Service: result
    Service-->>View: domain result
    View-->>Client: HTTP response

For read-only endpoints, the serializer validation step may be omitted and the view may go directly from request context to service/query to response serialization.

Permission model used by views

Base authentication

Most org endpoints require:

  • IsAuthenticated

Current-org scoping

Most org-specific endpoints also require:

  • HasCurrentOrg

This ensures the request is scoped to a resolved current organization before the endpoint proceeds.

Service-level role enforcement

Write and management endpoints do not rely on authentication alone. They delegate role checks to the service layer, mainly through:

  • services.membership.can_manage_members
  • services.membership.change_membership_role
  • services.membership.deactivate_membership
  • services.membership.reactivate_membership

This keeps permission rules centralized and testable.

Endpoint categories

Discovery endpoints

These help the frontend discover org context.

  • MyOrgsView
  • CurrentOrgDetailView
  • CurrentOrgBrandingView

Membership administration endpoints

These are for internal org member management.

  • CurrentOrgMembersView
  • OrgMembershipRoleUpdateView
  • OrgMembershipDeactivateView
  • OrgMembershipReactivateView

Customer visibility endpoints

These expose linked customer-organization data to internal org admins.

  • CurrentOrgCustomerLinksView
  • CurrentCustomerOrgMembersView

Design notes

Why views call services even for “simple” operations

Even when an operation looks simple, the service layer keeps:

  • org lookup rules centralized
  • role enforcement consistent
  • owner-safety rules out of views
  • future changes easier to make without touching HTTP code

This is especially important for membership workflows where mistakes could create security issues.

Why org update and org branding update are separate views

The app treats these as distinct concerns:

  • current org detail update = broader organization settings
  • current org branding update = branding/document-identity management

Keeping them separate gives:

  • clearer API boundaries
  • smaller payloads per screen
  • easier permission tightening later if needed

Why customer views are read-first

Customer-link and customer-membership endpoints are currently read-oriented because visibility is the immediate need. Write flows such as create/deactivate link can be added later once the underlying workflows are finalized.

Likely future additions

As the orgs app grows, likely view additions include:

  • organization create endpoint
  • customer-link create/deactivate endpoints
  • membership add/create endpoint
  • ownership transfer endpoint
  • org hierarchy/tree endpoint
  • customer membership management endpoints

The current split into organizations.py, memberships.py, and customers.py is intended to support that growth cleanly.