Skip to content

Partners service

Partners are Tomoda's multi-tenant scoping anchor: merchants, advertisers, organizations, or any other non-user entity that needs its own data and its own group of operators. Access to a partner is granted via PartnerMembership rows, not via the global User.Role field — so a standard user can also be a partner Tomoda account, and an account_type = partner account doesn't automatically have access to any specific partner until a membership is created.

Source file Purpose
backend/internal/models/partner.go Partner, PartnerMembership, PartnerStatus, PartnerMembershipRole, PartnerMemberView
backend/internal/services/partner/store.go CRUD + membership + "≥1 owner" invariant, partner.ErrLastOwner
backend/internal/services/partner/service.go Slug validation, creator-becomes-owner rule
backend/internal/services/partner/handler.go REST endpoints
backend/internal/services/partner/routes.go partner.Routes: the workspace route table, each entry naming its capability
backend/internal/access/authorizer.go Membership check for partner capabilities

Data model

Partner (id, slug, name, status, timestamps)
  └─ PartnerMembership (partner_id, user_id, role)
       role ∈ {owner, admin, member}
       UNIQUE (partner_id, user_id)
  • slug is unique, URL-safe (lowercase alphanumerics + hyphens, 2-64 chars), but routes use {partner_id} (UUID) rather than slug: the slug is for display.
  • status is active or suspended (PartnerStatus), defaulting to active via the model's BeforeCreate hook. It records operational state; the access gates key off membership + role, not status.

See architecture/data-model.md → Partners for the cross-domain view.

Membership roles

Distinct from the global UserRole enum — these mean different things.

Role Allowed actions
owner Billing, delete partner, manage other owners/admins/members. ≥1 required.
admin Manage members and all partner resources.
member Manage resources; cannot manage members or billing.

The member role was called staff. Rows keep storing staff and the code reads it as member, so the previous release still reads every membership; a later release rewrites the rows and writes member.

Access gates

Workspace routes are the table partner.Routes; each entry names a partner capability and is mounted with Authorizer.Require, which reads {partner_id} from the route and looks up the caller's membership (and the workspace status) in one query. See Access control.

Capability Allowed roles Use for
partner.workspace.read owner, admin, member Read-only partner views
partner.workspace.action.manage owner, admin Write, member management
partner.billing.action.manage owner Delete partner, billing, owner management

One DB read per request. A membership rejection or a suspended workspace returns 403. Cache (e.g. Redis partner_membership:<p>:<u> with invalidation on add/remove/role-change) is a follow-up if this becomes a hot path.

On success the gate places partner_id and partner_role onto the request context (api.WithPartner), read downstream via api.PartnerID(r) and api.PartnerRole(r).

Routes

All routes require JWT auth via the standard JWTAuth middleware.

Unscoped

Method Path Auth Purpose
POST /api/v1/partners any authenticated Create a partner; caller becomes owner
GET /api/v1/me/partners any authenticated List partners I belong to

Scoped — /api/v1/partner/{partner_id}/...

Every route names its capability in partner.Routes.

Method Path Required role Purpose
GET /api/v1/partner/{partner_id} any member Get the partner
GET /api/v1/partner/{partner_id}/members any member List members
PATCH /api/v1/partner/{partner_id} admin Update name, status
POST /api/v1/partner/{partner_id}/members admin Add a member
PATCH /api/v1/partner/{partner_id}/members/{user_id} admin Change a member's role
DELETE /api/v1/partner/{partner_id}/members/{user_id} admin Remove a member
DELETE /api/v1/partner/{partner_id} owner Delete the partner

Invariants

The store (backend/internal/services/partner/store.go) enforces these at the storage layer inside transactions so concurrent writes can't violate them:

  • ≥1 owner per partner. RemoveMember and UpdateMemberRole return partner.ErrLastOwner when the change would leave the partner without an owner. The handler translates this to 409 Conflict.
  • Creator becomes the first owner. Service.Create inserts the partner, then a membership with role=owner, and rolls back the partner row (best-effort Delete) if the membership insert fails.
  • One membership per (partner, user). Enforced by the composite unique index on (partner_id, user_id).

Frontend wiring

File Role
frontend/services/partnerService.ts REST client matching the route table above
frontend/hooks/usePartners.ts TanStack Query hook (partnersQueryKey) fetching /me/partners; exposes partners, membershipFor, roleFor, refresh
frontend/hooks/useAccess.ts inPartner, canAdminPartner, canOwnPartner helpers (alongside the Tomoda-team flags)
frontend/app/partner/ Partner ops shell under /partner (dashboard, members, events, hub); placeholder screens today

There is no "current partner" state in the frontend; partner context on the API side is always URL-derived.