Permissions Catalog (Modules & Per-Module Permission Keys)

Related documentation: Permissions Blueprint · Commercial Model · Backend Core Modules · Backend Core Addons

Permissions Catalog Specification

This page is the catalog of modules and per-module permission keys for the Kisum platform.

It is the source of truth for:

• which modules exist
• which type each module is (Base or Add-on)
• which permission keys belong to each module
• which cross-module flows justify the split between persona modules

This page complements (it does not replace):

• Permissions Blueprint — naming rules, layers, scope, delegation
• Commercial Model — package / module / add-on commercial relationships
• Backend Core Modules — module catalog inside Backend-Kisum-Core
• Backend Core Addons — add-on catalog inside Backend-Kisum-Core

Implementation status (2026-07-14): the persona-scoped catalog and Promoters Permissions V2 are implemented. Legacy basic.* values remain historical only; new runtime authorization uses promoter.*, artist.*, venue.*, finance.*, ai.*, and middle_agency.*. The completed order was Core catalog, Auth catalog, domain enforcement, frontend consumption, then legacy compatibility cleanup.

---

1. Module taxonomy

The platform separates modules into two hard categories. The category controls how the module is sold and how it relates to permissions.

1.1 Base modules

A Base module is a primary persona surface. It is the entry point that gives a company an operational identity in Kisum.

A company holds exactly one Base module — its persona. A company is a promoter or a venue or an artist agency or a vendor, never two at once. A business that genuinely operates as two personas creates a second company.

This is enforced, not conventional: Core’s company_subscriptions carries a unique index allowing one base subscription with commercial access per company (migration 00022), and UpsertBasicSubscription deactivates the previous base package when a new one is activated. Changing persona means deactivating the old base package and activating the new one — the subscription history is preserved.

The company’s single persona is exposed as audience on GET /internal/companies/{companyId}/entitlements, and Auth turns it into packageAppUrl on /auth/me/access. That is the platform’s answer to “which app owns this company” — there is no separate “main app” field.

Module key	Display name	Persona / surface
promoter	Promoters	Core App, Promoter base — events, calendar, artist offers, venue bookings
venue	Venue Management	Venue-side surface — venue/space management, availability, bookings, deals
artist	Artist Relations	Artist/agent-side surface — roster, availability, offers received, deals
vendor	Vendors	Vendor-side surface — vendor directory and vendor-side workflows (TBD)

Legacy note: the previous basic module is being renamed/replaced by the promoter module. The two are not commercially the same — promoter is one persona among four. Treat basic.* as legacy wherever it still appears in code or DB.

1.2 Add-ons

An Add-on is an optional capability layered onto a Base module. Add-ons do not make sense without a Base module owning the parent context.

Module key	Display name	Notes
finance	Finance	Owned by Backend-Kisum-Finance / Frontend-Kisum-Finance
touring	Touring	Touring/logistics workflows
ai	AI	AI Copilot, AI reports, AI forecasts
venue_marketplace	Venue Marketplace (booking)	Marketplace-style venue discovery + booking; distinct from Base venue
ticketing	Ticketing	Box-office engine (repo Backend-Nextkt) — now a standalone platform with its own role-based auth. Not seeded in Kisum Auth; Kisum integrates as a white-label partner. See §5.5.

1.3 Each Base module composes its own add-ons

A Base module is the parent commercial product. Add-ons attach onto Base modules, not the other way around. Compatibility is decided per add-on (see Backend Core Addons).

Base module (promoter | venue | artist | vendor)
  └── eligible add-ons (finance | touring | ai | venue_marketplace | …)

---

2. Cross-module flows (why Base modules are separated)

Persona modules exist as separate modules because their state machines own different data and different permissions at each stage of a deal. The two flows below justify the persona split.

2.1 Artist → Promoter flow

Flow stage	Artist / Agent access	Promoter access
Availability posted	Manage own availability	View availability
Offer sent	View / manage received offer	View / manage sent offer
Offer accepted	Deal becomes confirmed	Event changes from pending to confirmed
Deal confirmed	View / manage deal, contract, limited event data	Manage event, finance, ticket sales, contract
Event active	View restricted event data	Full event management

2.2 Promoter → Venue flow

Flow stage	Venue access	Promoter access
Venue created	Manage venue profile and spaces	View venue profile and spaces
Availability posted	Manage own availability	View availability
Booking requested	View / manage received booking	View / manage own booking request
Booking accepted	Deal becomes confirmed	Event is linked to confirmed venue deal
Deal confirmed	Manage deal and contracts	View deal and contracts
Event active	View promoter / event context if shared	Manage event from promoter side

The same business event (an offer, a booking, a deal, a contract) appears on two persona surfaces with different permissions on each side. That is the reason promoter, artist, and venue MUST stay as separate modules with their own permission namespaces.

---

3. Permission naming inside the catalog

Permission keys MUST follow the rules from the Permissions Blueprint:

<module>.<resource>.<action>

• module MUST equal one of the keys in §1.1 or §1.2 (e.g. promoter, venue, artist, vendor, finance, ai, touring, venue_marketplace, ticketing).
• Persona modules (promoter, venue, artist, vendor) own the persona-side actions for shared business objects (offers, bookings, deals, contracts, events). The same business object can appear in two namespaces (e.g. promoter.artist.offer.edit vs artist.offer.manage) — this is intentional; each side has its own permissions.
• Add-on modules (finance, ai, touring, venue_marketplace) own their own resources and actions; they do not embed persona terms in their keys.

---

4. Base module permissions

4.1 Module promoter (Core App, Promoter base — replaces legacy basic)

The promoter module is the primary surface of Backend-Kisum / Frontend-Kisum for promoter companies. It owns:

• promoter dashboard and workspace
• promoter company settings
• promoter events (and their per-tab management)
• promoter-side artist relations (offers, deals, contracts towards artists)
• promoter-side venue relations (bookings, deals, contracts towards venues)
• promoter-side vendor directory
• promoter calendar / availability

Permission key	What it gates
promoter.dashboard.view	Open promoter dashboard and analytics widgets
promoter.workspace.view	View company workspace, offers, news, AI panel
promoter.workspace.edit	Manage workspace settings and workspace-level offers
promoter.company.view	View company settings, members, roles, permissions
promoter.company.edit	Manage company settings, members, roles, permissions
promoter.news.view	View promoter / company news
promoter.ai.view	Access Kisum AI features
promoter.event.view	View promoter events list and event details
promoter.event.edit	Create / update / delete promoter events and edit tabs
promoter.event.sales.view	View ticket sales summary and basic event commercial report
promoter.event.sales.edit	Post / update ticket sales numbers
promoter.event.estimate.view	View estimated event costs
promoter.event.estimate.edit	Post / update estimated event costs
promoter.event.analytics.view	View event analytics
promoter.event.commercial.view	View event commercial tab
promoter.event.commercial.edit	Manage event commercial tab
promoter.event.marketing_sales.view	View marketing and sales tab
promoter.event.marketing_sales.edit	Manage marketing and sales tab
promoter.event.talent_programming.view	View talent and programming tab
promoter.event.talent_programming.edit	Manage talent and programming tab
promoter.event.venue_site.view	View venue and site tab
promoter.event.venue_site.edit	Manage venue and site tab
promoter.event.hospitality_logistics.view	View hospitality and logistics tab
promoter.event.hospitality_logistics.edit	Manage hospitality and logistics tab
promoter.event.technical_infrastructure.view	View technical and infrastructure tab
promoter.event.technical_infrastructure.edit	Manage technical and infrastructure tab
promoter.event.safety_compliance.view	View safety and compliance tab
promoter.event.safety_compliance.edit	Manage safety and compliance tab
promoter.event.operations_management.view	View operations and management tab
promoter.event.operations_management.edit	Manage operations and management tab
promoter.event.general_administrative.view	View general and administrative tab
promoter.event.general_administrative.edit	Manage general and administrative tab
promoter.event.other.view	View other event sections
promoter.event.other.edit	Manage other event sections
promoter.artist.view	View artist / agent list, profile, public roster details
promoter.artist.availability.view	View artist availability blocks
promoter.artist.offer.view	View offers sent to artists / agents
promoter.artist.offer.edit	Create / edit / cancel / manage pending offers to artists
promoter.artist.deal.view	View confirmed artist deal details
promoter.artist.contract.view	View contracts linked to confirmed artist deals
promoter.artist.contract.edit	Upload / edit / sign / manage contracts for artist deals
promoter.venue.view	View venue list, venue profile, public venue details
promoter.venue.space.view	View spaces inside a venue
promoter.venue.availability.view	View venue availability blocks
promoter.venue.booking.view	View venue booking requests made by promoter
promoter.venue.booking.edit	Create / edit / cancel venue booking requests
promoter.venue.deal.view	View confirmed venue deal details
promoter.venue.contract.view	View contracts linked to confirmed venue deals
promoter.vendor.view	View vendor directory
promoter.vendor.edit	Create / update / delete promoter-side vendor records
promoter.calendar.view	View promoter availability / calendar
promoter.calendar.edit	Manage promoter availability blocks

Promoter middle-agent buyer keys moved to middle_agency.* (2026-06-26) — see §4.5.

4.1.1 Notes on promoter.artist.* and promoter.venue.*

These are promoter-side permissions to act on artist relations and venue relations. They do NOT grant access to the artist’s own surface or the venue’s own surface — those live under the artist.* and venue.* modules and are gated by the other side’s permissions.

4.1.2 Promoters scoped authorization (implemented)

The Promoters permission redesign uses five required layers: company entitlement, user module grant, action permission, data scope, and workflow rule. Missing any layer denies the action. Frontend menu visibility is not the security boundary.

• Mutable resources use separate view, create, edit, and delete actions. High-risk transitions use explicit actions such as submit, approve, send, confirm, cancel, settle, and export.
• Core owns customizable business-unit master data. Auth owns business-unit memberships, shared teams, scoped grants, individual allow/deny overrides, Finance roles, and approval limits.
• A user may join multiple business units and teams. Team grants are additive; an explicit individual deny wins.
• Event scope may be company-wide, business-unit events, or assigned events only. Event subsection grants remain separate so financial, production, hospitality, talent, and other teams do not receive the entire Event record automatically.
• Finance roles and approval limits may differ by business unit. Promoters Event permissions never grant Finance approval authority.
• Promoter artist/agency and venue directories remain read-only master-data surfaces. Booking, offers, enquiries, and venue requests use promoter workflow permissions, not the artist or venue persona modules. Direct Promoters master-data writes to /api/artists* or /api/venues* return 410 Gone.
• Promoters Users & Access must only present Promoters-managed namespaces. It may assign Promoters-side access, add-on toggles, and Middle Agency access where relevant, but it must not expose or overwrite artist.* or venue.* persona permissions owned by the other apps.

The implemented catalog is seeded by Auth and mapped to Promoters and Finance routes. Frontend-Kisum-Promoters/PERMISSIONS_MATRIX.md is the maintained human-readable matrix; automated route coverage prevents new business routes from bypassing the catalog.

4.2 Module artist (Artist Relations — design-only, permissions seedable)

The artist module is the artist/agent persona surface. The frontend/backend implementation is TBD, but the permission catalog below MUST be seeded so that future code accepts these keys without rework.

Permission key	What it gates
artist.view	View artist / agent profile, roster, public artist details
artist.edit	Create / update / delete artist profiles or roster data
artist.profile.view	View artist / agent business profile
artist.profile.edit	Edit artist / agent business profile
artist.availability.view	View availability blocks
artist.availability.edit	Create / update / delete availability blocks
artist.availability.offer.view	View offers received for availability blocks
artist.availability.offer.manage	Accept / reject / counter offers received for availability blocks
artist.promoter.view	View promoter profile linked to an offer / deal / event
artist.offer.view	View marketplace offers received by the artist / agent
artist.offer.manage	Accept / reject / counter / manage artist-side offers
artist.deal.view	View confirmed deal details
artist.deal.manage	Manage confirmed deal details
artist.contract.view	View contracts linked to confirmed deals
artist.contract.manage	Issue / upload / edit / sign contracts
artist.event.view	View linked promoter event details after offer / deal is created
artist.event.finance.view	View restricted event finance summary, ticket sales, gross sales, basic settlement data
artist.event.ticket.view	View restricted ticket sales / reporting for linked events
artist.event.production.view	View restricted production / event info shared by promoter
artist.message.view	View communications / messages with promoters
artist.message.send	Send messages to promoters

4.5 Module middle_agency (Middle Agent Workspace addon — 2026-06-26)

Org-level Core addon (middle_agency). Replaces bundled artist.middle_* and promoter.middle_agent.*. Requires active company_addons row before Auth grants apply.

Namespace	Examples	Notes
middle_agency.workspace.*	view, edit	Workspace profile + dashboard
middle_agency.roster.*	view, create, edit, delete, publish, verify_request	Private workspace artist cards
middle_agency.offer.*	view, create, send_to_source, send_to_buyer, confirm, source_fee.view, margin.view, commission.*	Dual-sided offers; financial keys gate redaction
middle_agency.calendar.*	view, edit, hold.create/confirm/release	Opportunity calendar (not official availability)
middle_agency.contact.*	view, create, edit, delete	Contact book
middle_agency.document.*	view, upload, send, delete	Offer documents
middle_agency.settlement.*	view, edit, approve	Settlement read model
middle_agency.reports.*	view, export	Pipeline / conversion / commission reports
middle_agency.source_inbox.*	view, respond	Direct reps respond to inbound source offers
middle_agency.partner.manage	—	Approve/block/prefer middle-agent partners
middle_agency.listing.view	—	Promoter: browse non-direct marketplace listings
middle_agency.enquiry.create	—	Promoter: submit enquiries
middle_agency.enquiry.view	—	Promoter: buyer-safe enquiry status

4.2.1 Middle Agent Workspace (artist.middle_*) — superseded

Removed 2026-06-26. Use middle_agency.* (§4.5). Migration: Auth 000014_middle_agency_permissions.up.sql + migrate-permissions.

Seeded in Backend-Kisum-Auth (2026-06-25). Governs the parallel non-direct agency workflow in Backend-Kisum-Artists — distinct from direct booking_requests / booking_offers.

Namespace	Examples	Notes
artist.middle_workspace.*	view, edit	Workspace profile + dashboard
artist.middle_roster.*	view, create, edit, delete, publish, verify_request	Private workspace artist cards
artist.middle_offer.*	view, create, send_to_source, send_to_buyer, confirm, source_fee.view, margin.view, commission.*	Dual-sided offers; financial keys gate redaction
artist.middle_calendar.*	view, edit, hold.create/confirm/release	Opportunity calendar (not official availability)
artist.middle_contact.*	view, create, edit, delete	Contact book
artist.middle_document.*	view, upload, send, delete	Offer documents
artist.middle_settlement.*	view, edit, approve	Settlement read model
artist.middle_reports.*	view, export	Pipeline reports
artist.middle_source_inbox.*	view, respond	Source inbox
artist.middle_partner.manage	—	Partner rules

Full seed list: Backend-Kisum-Auth/cmd/migrate-permissions/seed.go (middle_agency block). Platform: Middle Agent Workspace.

4.3 Module venue (Venue Management — Backend-Kisum-Venues / Frontend-Kisum-Venues)

The venue module is the venue-side surface. It is the first-class management module for venue companies. It is distinct from the venue_marketplace add-on and from promoter.venue.* (which are the promoter-side counterparts).

Permission key	What it gates
venue.venue.view	View venue list and venue details
venue.venue.edit	Create / update / delete venue profile
venue.profile.view	View venue business profile
venue.profile.edit	Edit venue business profile
venue.space.view	View spaces inside a venue
venue.space.edit	Create / update / delete venue spaces
venue.availability.view	View venue availability blocks
venue.availability.edit	Create / update / delete venue availability blocks
venue.booking.view	View bookings received by the venue
venue.booking.manage	Accept / reject / cancel / manage venue bookings
venue.promoter.view	View promoter profile linked to booking / deal / event
venue.deal.view	View confirmed venue deal details
venue.deal.manage	Manage confirmed venue deal details
venue.contract.view	View contracts linked to venue bookings / deals
venue.contract.manage	Issue / upload / edit / sign contracts
venue.customer.view	View customer / client overlays
venue.customer.edit	Edit customer / client overlays
venue.message.view	View communications / messages with promoters
venue.message.send	Send messages to promoters

4.4 Module vendor (TBD)

The vendor module is reserved for the vendor persona. Permission keys are not yet defined in this catalog — they MUST follow the same vendor.<resource>.<action> shape when added.

Until vendor permissions are defined, vendor-related actions on the promoter side are gated by promoter.vendor.view and promoter.vendor.edit (see §4.1).

---

5. Add-on module permissions

5.1 Module finance (Owned by Backend-Kisum-Finance / Frontend-Kisum-Finance)

Permission key	What it gates
finance.invoice.view	View invoices
finance.invoice.edit	Create / update invoices
finance.invoice.approve	Approve invoices (needs membership approval_limit)
finance.bill.view	View bills
finance.bill.edit	Create / update bills
finance.bill.approve	Approve bills (needs membership approval_limit)
finance.vendor.view	View vendor master
finance.vendor.edit	Manage vendor master
finance.settlement.view	View settlements / payouts
finance.settlement.edit	Manage settlements
finance.report.view	View finance reports / P&L

finance.*.approve actions REQUIRE the membership-level approval_limit field in addition to the permission grant. Permission alone is not sufficient to approve.

These keys are derived, not ticked

No screen grants finance.* individually. Auth derives them from the roles set in the persona app’s member editor — organization level plus the per-business-unit role — in effectiveAccessV2. See Permissions derived from the organization level for the exact mapping.

Consequences worth knowing:

• Granting the Finance module alone gives no Finance access. A business-unit assignment (or a company-level admin role) is what produces the keys.
• Changing someone’s business-unit role changes their Finance permissions on the next /auth/me/access — nothing is stored per user and nothing needs re-saving.
• An explicit user-level deny still overrides a derived key.
• The Finance dashboard (/api/dashboard/*) is reachable with any Finance read key. It is the landing page, not a report; its rows are already narrowed per user. Only /api/reports/* requires finance.report.view.

5.2 Module ai

Permission key	What it gates
ai.copilot.use	Use the AI Copilot / chat
ai.report.view	View AI-generated reports / forecasts
ai.report.run	Trigger an AI report job

5.3 Module touring (TBD)

Permission keys for touring.* are reserved. Conceptual scope (per the Backend Core Modules page): routing, logistics, travel/accommodation coordination, operational touring workflows.

5.4 Module venue_marketplace (TBD)

Permission keys for venue_marketplace.* are reserved. Conceptual scope: marketplace-style venue discovery and booking. Distinct from the Base venue module (which is the venue-side management surface).

5.5 Module ticketing (built backend Backend-Nextkt — catalog NOT yet seeded)

The ticketing box-office engine became a standalone platform (repo Backend-Nextkt) with its own auth and tenancy. It resolves the ticketing.* keys below in-code from the member’s role (OWNER → all, MANAGER → all but settings.manage, STAFF → view + guestlist + scan; system admins → all). They are not seeded into Kisum Auth — this list is kept for cross-reference only. Kisum integrates as a white-label partner (per-org API key); it does not entitle ticketing through Core/Auth. Canonical doc: Ticketing Addon Backend (Backend-Nextkt).

Permission key	What it gates
ticketing.event.view	View ticketing events, maps, allocations granted to my company
ticketing.event.manage	Create / update ticketing events, host-mode, maps, uploads, allocations
ticketing.inventory.view	View ticket types / inventory
ticketing.tier.manage	Create / update / delete ticket types, products, complimentaries
ticketing.hold.manage	Place operator inventory holds
ticketing.sale.view	View reservations, manual sales, discount codes
ticketing.sale.manage	Record manual sales, cancel, reassign, manage discount codes
ticketing.sale.refund	Refund reservations; review refund requests
ticketing.guestlist.view	View guest-list entries
ticketing.guestlist.manage	Add guests (capacity-gated), set status, record arrivals
ticketing.scan.operate	Scan ticket codes at the door
ticketing.allocation.manage	Grant / revoke collaborator allocations (host → promoter)
ticketing.settings.manage	Manage per-tenant checkout settings (fees, platform fee, points, guest)
ticketing.report.view	Read ticketing sales / settlement reports (also accepted on the network BFF)

Buyer-facing storefront routes (/consumer/*) use the module’s own auth (x-tenant + optional buyer JWT), not these Kisum permissions — see the canonical doc.

---

6. Migration from legacy basic.*

The legacy basic module is being retired. The migration sequence is strict:

1. Core — register the new modules (promoter, artist, venue, vendor, plus add-ons) in Backend-Kisum-Core (modules + add-ons catalog).
2. Auth — replace the permission catalog in Backend-Kisum-Auth with the keys in §4 and §5. Drop legacy basic.* rows.
3. Backends — every backend service MUST update its permission checks to accept the new keys. No service may keep gating on basic.* after this step.
4. Frontends — every frontend MUST stop sending / expecting basic.* keys; align role/role-template seeds to the new namespaces.
5. Core cleanup — only after steps 1–4 are merged: remove the legacy basic module from Core.

This is a breaking migration: tokens, role templates, membership grants, and any cached permission state that contain basic.* will stop matching. Plan a coordinated rollout per the Permissions Blueprint layered model — no legacy basic.* should leak into a new public contract.

---

7. Summary

• Modules are split into Base (promoter, venue, artist, vendor) and Add-ons (finance, ai, touring, venue_marketplace). ticketing is now a standalone platform (own role-based auth, not seeded here) that Kisum integrates with as a white-label partner — see §5.5.
• A company picks a Base module to operate as a persona, then layers compatible Add-ons on top.
• Each persona has its own namespace because the same business object (offer, booking, deal, contract, event) shows up on two surfaces with different permissions on each side.
• Permission keys keep the <module>.<resource>.<action> shape from the Permissions Blueprint.
• basic.* is legacy and is replaced by promoter.* plus the new persona modules — migration is staged through Core → Auth → backends → frontends → Core cleanup.

Promoters V2 action families (2026-07-14)

The Auth catalog includes separate lifecycle actions for company members, teams, business units, vendors, events, tours, event sales, estimates, commercial export, taxes, tickets, booking requests/offers/holds/confirmed/activity/Finance handoff/shortlists/relationships/templates, and promoter venue bookings. Artist, agency, venue directory, and venue marketplace master data remain view-only from Promoters. AI uses ai.copilot.use; existing middle_agency.* and finance.* namespaces remain canonical; Nextkt has no Kisum permission rows.

Each permission rule owns its scope (COMPANY, BUSINESS_UNIT, ASSIGNED_EVENT, or OWN_RECORD). Do not infer create, edit, delete, approve, sync, or export from a broad view/edit key.