Skip to content

Orgs — URLs

Responsibilities

The orgs URL configuration exposes the HTTP routes for:

  • listing the organizations available to the current user
  • reading and updating the current organization
  • reading and updating current organization branding
  • listing and managing internal org memberships
  • listing customer links for the current org
  • listing members of linked customer organizations

It is responsible for:

  • mapping stable route paths to views
  • naming routes for reverse lookup and tests
  • grouping organization and membership endpoints by domain

It is not responsible for:

  • validating input payloads
  • enforcing domain rules
  • resolving business permissions
  • implementing org or membership workflows

Those concerns live in serializers, services, and views.

Route groups

Organization routes

These routes expose org discovery and current-org settings.

orgs/me/

  • Name
  • orgs-my-orgs
  • View
  • MyOrgsView
  • Methods
  • GET
  • Purpose
  • list active organizations for the authenticated user

This is typically used by org-switching UI and bootstrap flows.

orgs/current/

  • Name
  • orgs-current-detail
  • View
  • CurrentOrgDetailView
  • Methods
  • GET
  • Purpose
  • return the full detail payload for the current organization

Requires request-scoped current-org resolution.

orgs/current/update/

  • Name
  • orgs-current-update
  • View
  • CurrentOrgUpdateView
  • Methods
  • PATCH
  • Purpose
  • update current organization detail/settings fields

This route is intended for org admins/owners.

orgs/current/branding/

  • Name
  • orgs-current-branding
  • View
  • CurrentOrgBrandingView
  • Methods
  • GET
  • Purpose
  • return current organization branding/document identity payload

This route is useful for org settings screens and PDF/report branding previews.

orgs/current/branding/update/

  • Name
  • orgs-current-branding-update
  • View
  • CurrentOrgBrandingUpdateView
  • Methods
  • PATCH
  • Purpose
  • update current organization branding/document identity fields

This is the narrower update path for branding administration.

Membership routes

These routes expose current org member listing and management.

orgs/current/members/

  • Name
  • orgs-current-members
  • View
  • CurrentOrgMembersView
  • Methods
  • GET
  • Purpose
  • list active internal members of the current organization

This is the main member directory endpoint.

orgs/members/<int:membership_id>/role/

  • Name
  • orgs-membership-role-update
  • View
  • OrgMembershipRoleUpdateView
  • Methods
  • PATCH
  • Path parameters
  • membership_id
  • Purpose
  • change the role of one org membership

Role-management rules are enforced in the membership service.

orgs/members/<int:membership_id>/deactivate/

  • Name
  • orgs-membership-deactivate
  • View
  • OrgMembershipDeactivateView
  • Methods
  • POST
  • Path parameters
  • membership_id
  • Purpose
  • deactivate one org membership

This is the soft-removal path for internal org members.

orgs/members/<int:membership_id>/reactivate/

  • Name
  • orgs-membership-reactivate
  • View
  • OrgMembershipReactivateView
  • Methods
  • POST
  • Path parameters
  • membership_id
  • Purpose
  • reactivate one org membership

This restores an inactive membership without creating a new row.

Customer routes

These routes expose linked customer-org visibility from the perspective of the current internal org.

orgs/current/customers/

  • Name
  • orgs-current-customer-links
  • View
  • CurrentOrgCustomerLinksView
  • Methods
  • GET
  • Purpose
  • list customer organizations linked to the current internal org

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

orgs/current/customers/<int:customer_org_id>/members/

  • Name
  • orgs-current-customer-members
  • View
  • CurrentCustomerOrgMembersView
  • Methods
  • GET
  • Path parameters
  • customer_org_id
  • Purpose
  • list active members of a linked customer organization

This route only works if an active CustomerLink exists between the current org and the target customer org.

URL relationship overview

flowchart TD
    URLConf["orgs/urls.py"]

    OrganizationRoutes["Organization routes"]
    MembershipRoutes["Membership routes"]
    CustomerRoutes["Customer routes"]

    URLConf --> OrganizationRoutes
    URLConf --> MembershipRoutes
    URLConf --> CustomerRoutes

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

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

    CustomerRoutes --> CurrentOrgCustomerLinksView["CurrentOrgCustomerLinksView"]
    CustomerRoutes --> CurrentCustomerOrgMembersView["CurrentCustomerOrgMembersView"]

Routing style

The orgs app uses explicit path(...) mappings for all endpoints.

This is intentional because: - the number of endpoints is still small and focused - each route has a clear and distinct responsibility - route names are heavily used in tests - explicit paths are easier to reason about than introducing a router for a limited set of non-viewset actions

Reverse lookup examples

These route names are intended to remain stable because they are used by tests and likely by frontend consumers indirectly through backend integration.

Organization routes

  • reverse("orgs-my-orgs")
  • reverse("orgs-current-detail")
  • reverse("orgs-current-update")
  • reverse("orgs-current-branding")
  • reverse("orgs-current-branding-update")

Membership routes

  • reverse("orgs-current-members")
  • reverse("orgs-membership-role-update", kwargs={"membership_id": ...})
  • reverse("orgs-membership-deactivate", kwargs={"membership_id": ...})
  • reverse("orgs-membership-reactivate", kwargs={"membership_id": ...})

Customer routes

  • reverse("orgs-current-customer-links")
  • reverse("orgs-current-customer-members", kwargs={"customer_org_id": ...})

Current-org dependency

Most orgs routes depend on request-scoped current-org resolution.

That generally means requests must include the organization context expected by the rest of the backend, such as: - X-ORG-ID - optionally X-ORG-SLUG

If this context is missing or invalid, current-org-protected views will fail before entering their domain logic.

This is especially important for: - orgs/current/* - orgs/current/members/* - orgs/current/customers/*

Route categories by usage

Discovery / bootstrap usage

These routes help clients establish org context. - orgs/me/ - orgs/current/

Org settings administration

These routes are used by org settings screens. - orgs/current/update/ - orgs/current/branding/ - orgs/current/branding/update/

Internal member administration

These routes manage internal org members. - orgs/current/members/ - orgs/members/<membership_id>/role/ - orgs/members/<membership_id>/deactivate/ - orgs/members/<membership_id>/reactivate/

Customer visibility

These routes expose internal-org access to linked customer organizations. - orgs/current/customers/ - orgs/current/customers/<customer_org_id>/members/

Likely future additions

As the orgs app expands, likely future route additions include: - org creation endpoint - customer-link create/deactivate routes - membership create/add route - ownership transfer route - org hierarchy/tree route - customer membership management routes

The current path structure leaves room for that growth without breaking naming or route grouping conventions.