Backend Core API Contract (OpenAPI-Style)

Related documentation: Kisum System · Backend modules · Data ownership · Infrastructure tasks · Error contract

Contract Specification for Platform Core Internal API

Audience: backend engineers, platform-admin backend engineers, Auth backend engineers, QA, DevOps, integrators
Status: contract specification
Scope: this document defines the API contract for Platform Core. It focuses on:

exact endpoints
methods
required headers
auth model
request parameters
request bodies
response bodies
error responses
examples
integration rules

This is the API contract companion to:

Backend Implementation → master backend plan
Backend Auth → Auth backend/API specification
Backend Core → full engineering/backend specification (including section 6.4 on the mandatory companies table in Core DB)

Company paths in this API

Path parameters such as {companyId} refer to rows in Core.companies.id. Platform Core is the source of truth for the company master row and all commercial state linked to it. The tables that back those APIs (companies, company_subscriptions, company_addons, etc.) must exist as specified in Backend Core (sections 6.0 and 7)—that DDL is mandatory. See also Data ownership and Backend Core (section 6.4).

0. API overview

Platform Core is an internal-only backend service for every route under /internal/*.

It is not intended for direct browser/frontend access except for the small /public/* read-only catalog group added in the 2026-05-20 Trial Flags + Persona Pricing release — see section 0.1 below.

0.1 Public catalog routes (browser-facing, CORS-gated)

The /public route group is the one part of Platform Core that browsers may call directly. It exists so the marketing-site /pricing + /create pages can render persona tabs and decide trial-vs-paid signup without an intermediate BFF.

GET /public/packages?audience=promoter|venue[&key=…]
GET /public/addons?audience=promoter|venue[&keys=ai,finance]

Auth: none. CORS gated by CORS_PUBLIC_ORIGINS (comma-separated allow-list). When unset, Core falls back to the existing CORS_ORIGIN value so an ops-tuned origin list keeps working without a second env var. Both unset = fail-closed (no browser may reach /public/*).
Audience: required query param; 'promoter' or 'venue'. Other values → 400 validation_error.
Filters: packages support a single ?key= lookup; addons support ?keys=a,b,c. Both filter to is_active=true.
Response shape: slimmed view (publicPackageView / publicAddonView in internal/httpapi/public_catalog.go) — tax_code and internal flags are stripped so a future Core schema addition cannot accidentally leak.

{
  "success": true,
  "data": {
    "packages": [{
      "id": "…", "key": "basic_promoter", "name": "Basic (Promoter)",
      "description": "…", "audience": "promoter",
      "priceMinor": 199.00, "currency": "USD", "billingInterval": "monthly",
      "taxInclusive": false,
      "trialEnabled": true, "trialDays": 14,
      "regionPricing": [], "modules": ["basic","ai","finance"]
    }]
  }
}

Every other Core route stays under /internal/* and requires X-Internal-API-Key.

Its main responsibilities are:

storing company master records and company profile/business metadata
storing company addresses, social links, and company documents
returning company commercial entitlements
returning catalog definitions (modules/packages/add-ons)
storing and updating package/add-on/subscription state
bumping entitlement versions for Auth cache invalidation
sending Core-owned commercial lifecycle email after successful writes

Runtime implementation note

The current Backend-Kisum-Core service now exposes internal company-management routes in addition to the original catalog and entitlement endpoints. The live route surface is published in core-openapi.yaml and includes:

POST /internal/companies
GET/PATCH /internal/companies/{companyId}
GET/POST /internal/companies/{companyId}/business-units
PATCH /internal/business-units/{businessUnitId}
GET/PUT /internal/companies/{companyId}/profile
GET/POST/PATCH/DELETE company address routes
GET/POST/DELETE company social-link routes
GET/POST/DELETE company document routes
the existing entitlements, subscription-summary, history, Basic, and add-on endpoints

These routes are internal-only and require X-Internal-API-Key matching CORE_INTERNAL_API_KEY.

0.0.2 Core email behavior

Core uses AWS SES only for commercial lifecycle email.

Current implemented email triggers:

POST /internal/companies
- sends company-created email when the resulting company profile contains an email
PATCH /internal/companies/{companyId}
- sends company-status-changed email only when status actually changes and the resulting company profile contains an email
POST /internal/companies/{companyId}/basic
- sends base-subscription-updated email when the resulting company profile contains an email
POST /internal/companies/{companyId}/addons
- sends add-on-updated email when the resulting company profile contains an email

Important rules:

email is best-effort and asynchronous
the PostgreSQL write remains the source of truth
SES failure must not roll back the business write
no email is sent when the company has no profile email

0.0.1 What the company sub-resource endpoints are for

These endpoints exist because Core owns more than subscriptions. Core also owns the normalized company master structure, so company business metadata does not have to be flattened into one row or mixed into Auth/Base ownership.

`PUT /internal/companies/{companyId}/profile`

Purpose:

store or replace the company’s descriptive business profile

Use this endpoint when:

a company website, phone, timezone, industry, or description must be saved
a public company slug or brand logo URL must be saved as first-class profile fields
onboarding/admin flows need to enrich the company after the root company row already exists
descriptive company metadata should be updated without changing subscriptions or entitlements

Backed by:

company_profiles

Why this exists:

the root companies row is the commercial identity anchor
the profile is optional descriptive metadata
profile data changes independently from commercial state

Integration note:

the same profile object may also be sent inline during POST /internal/companies
during nested company edit payloads, profile is treated as an upsert

`GET /internal/companies/{companyId}/business-units`

Purpose:

list Core-owned business-unit master rows for one company

Backed by:

business_units

Important rule:

this returns business-unit master data only
it does not return business-unit memberships
memberships remain Auth-owned

`POST /internal/companies/{companyId}/business-units`

Purpose:

create one Core-owned business-unit master row under a company

Backed by:

business_units

Important rule:

this creates business-unit identity only
it does not create memberships

`PATCH /internal/business-units/{businessUnitId}`

Purpose:

update one Core-owned business-unit master row

Backed by:

business_units

Important rule:

this updates the business-unit master row only
business-unit membership remains in Auth

`POST /internal/companies/{companyId}/addresses`

Purpose:

create a structured address record for the company

Use this endpoint when:

the company needs a legal, billing, mailing, or office address
the company needs more than one stored address
platform staff needs to mark or replace the primary address later

Backed by:

company_addresses

Why this exists:

addresses are one-to-many structured records
addresses should not be stored as free text in the profile
address lifecycle is different from profile and entitlement lifecycle

Integration note:

addresses may also be sent inline during POST /internal/companies
when nested addresses are sent during company edit, the list is synchronized against company_addresses
rows with id are updated, rows without id are inserted, and rows omitted from the submitted list are removed

`POST /internal/companies/{companyId}/social-links`

Purpose:

Use this endpoint when:

the company has official Instagram, LinkedIn, website-like public profile links, or similar branded destinations
admin/onboarding flows need a normalized list of public links

Backed by:

company_social_links

Why this exists:

a company may have many links
links are repeatable structured records
they should not be flattened into a single text field in the profile

Integration note:

social links may also be sent inline during POST /internal/companies
when nested social links are sent during company edit, the list is synchronized against company_social_links
rows with id are updated, rows without id are inserted, and rows omitted from the submitted list are removed

`POST /internal/companies/{companyId}/documents`

Purpose:

Use this endpoint when:

legal/compliance/reference company documents need to be linked to the company
another internal system uploads a file and Core must track that relationship
platform staff needs a structured document registry under the company

Backed by:

company_documents

Why this exists:

documents are one-to-many records
the actual binary may live in external storage while Core stores the association and metadata
document lifecycle is separate from company profile text or subscription state

Integration note:

documents may also be sent inline during POST /internal/companies
when nested documents are sent during company edit, the list is synchronized against company_documents
rows with id are updated, rows without id are inserted, and rows omitted from the submitted list are removed

0.1 Runtime position in the platform

Platform Core is the commercial entitlement backend.

It is positioned in the runtime architecture as follows:

Auth Backend = identity, memberships, grants, permissions, delegation
Platform Core Backend = packages, add-ons, subscriptions, company entitlements
Base / Module Backends = business logic and enforcement
Frontend = consumes resolved access for UX, but is not the source of truth

Main runtime rule

Platform Core does not compute final user access.

The main access rule remains:

effective_access = company_entitlements ∩ membership_grants

Where:

company_entitlements come from Platform Core
membership_grants come from Auth
final effective_access is computed by Auth

Important implication

Platform Core must not be used by frontend or business backends as a replacement for Auth when making user-level access decisions.

Platform Core only answers:

What does this company commercially own right now?

It does not answer:

whether a specific user can use a module
whether a specific permission is granted
whether a specific actor can delegate access

0.2 Request ownership and primary callers

Platform Core does not define the canonical tenant header for runtime access enforcement. That standard is x-org, defined by Auth/Base/module integration contracts.

Frontend should not call Platform Core directly

Frontend should normally call:

Auth Backend
Base Backend
module backends
admin backend (where applicable)

Frontend should not call Platform Core directly to determine access.

Primary caller

The primary caller of Platform Core is:

Auth Backend

Especially for:

GET /auth/me/access
company-switch access refresh
access recomputation after entitlement changes

Secondary callers

Allowed secondary callers:

Platform Admin Backend
approved internal jobs/services

Non-primary callers

Business backends such as Base / Finance / Market / Touring / Venue / AI should not call Platform Core to compute final user authorization.

If a business backend needs user-level authorization, it must use Auth-resolved access context, not Core entitlements directly.

Clean runtime pattern

Frontend
  -> Auth
      -> Auth DB
      -> Platform Core
  <- resolved access result

This keeps Auth as the access aggregation layer and keeps Core focused on commercial entitlement truth.

0.3 Naming clarification

To avoid confusion across teams, use these terms consistently:

Basic Package → commercial product / subscription concept
Core App → the frontend/base application experience
Basic Backend → business backend for core platform features
Platform Core Backend → commercial entitlement backend

This avoids mixing:

Basic Package
Basic Backend
Platform Core Backend

which are not the same thing.

1. Base URL and exposure model

1.1 Recommended base URL

https://core.kisum.io

1.2 Exposure model

All routes in this spec are internal routes.

Allowed callers:

Auth Backend
Platform Admin Backend
approved internal jobs/services

Not allowed:

public frontend
public mobile apps
arbitrary public clients

Integration note

Platform Core is an internal service in the middle of an access-resolution chain.

Typical runtime chain:

Frontend -> Auth -> Platform Core

or for admin changes:

Platform Admin UI -> Platform Admin Backend -> Platform Core

Business backends should not bypass Auth and use Core as a user-authorization oracle.

2. Content type and response conventions

2.1 Request content type

All request bodies use:

Content-Type: application/json

unless explicitly noted otherwise.

2.2 Success envelope

All successful responses return:

{
  "success": true,
  "data": {}
}

2.3 Error envelope

All error responses return:

{
  "success": false,
  "error": {
    "code": "string_code",
    "message": "Human readable message"
  }
}

2.4 Standard error codes

Common error codes used by Platform Core:

unauthorized
forbidden
validation_error
not_found
conflict
not_ready
internal_error
service_unavailable

3. Internal authentication contract

3.1 Required authentication

All /internal/* routes must require internal service authentication.

Recommended first implementation:

X-Internal-API-Key: <secret>

Alternative future implementation:

Authorization: Bearer <internal-service-token>

3.2 Required behavior

If internal auth is missing or invalid:

return 401 unauthorized
do not expose data
do not leak internal routing details

Example error

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid internal credentials"
  }
}

4. Common object schemas

4.1 Module object

{
  "id": "uuid",
  "key": "finance",
  "name": "Finance",
  "type": "addon",
  "description": "Finance module",
  "isActive": true
}

Fields

id: UUID
key: canonical module key
name: display name
type: base or addon
description: optional description
isActive: boolean

4.2 Package object

{
  "id": "uuid",
  "key": "basic",
  "name": "Basic",
  "description": "Basic subscription that enables Core App",
  "isActive": true,
  "modules": ["basic"]
}

Fields

id
key
name
description
isActive
modules: array of module keys currently mapped to this package

4.3 Add-on object

{
  "id": "uuid",
  "key": "finance",
  "name": "Finance",
  "description": "Finance add-on",
  "isActive": true,
  "modules": ["finance"]
}

4.4 Company add-on summary

{
  "key": "finance",
  "status": "active",
  "startsAt": "2026-04-16T00:00:00Z",
  "endsAt": "2026-05-16T00:00:00Z"
}

4.5 Company entitlement object

{
  "companyId": "cmp_001",
  "hasBasic": true,
  "basePackage": "basic",
  "addons": [
    {
      "key": "finance",
      "status": "active",
      "startsAt": "2026-04-16T00:00:00Z",
      "endsAt": "2026-05-16T00:00:00Z"
    }
  ],
  "enabledModules": ["basic", "finance"],
  "entitlementVersion": 8,
  "updatedAt": "2026-04-16T05:00:00Z"
}

4.6 Entitlement history object

{
  "id": "uuid",
  "changeType": "addon_activated",
  "entityType": "addon",
  "entityKey": "finance",
  "previousStatus": "inactive",
  "newStatus": "active",
  "source": "platform_admin",
  "changedBy": "admin_user_uuid",
  "createdAt": "2026-04-16T05:00:00Z"
}

5. Health endpoints

5.1 `GET /health`

Purpose

Simple liveness probe.

Auth

No internal auth required, unless your infra policy requires all routes behind private network anyway.

Request body

No body.

Response — 200

{
  "success": true,
  "data": {
    "status": "ok"
  }
}

5.2 `GET /ready`

Purpose

Readiness probe.

Readiness checks

Must verify:

Core DB reachable
required config loaded
service initialized

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "status": "ready"
  }
}

Failure — 503

{
  "success": false,
  "error": {
    "code": "not_ready",
    "message": "core database unavailable"
  }
}

6. Catalog read endpoints

6.1 `GET /internal/catalog/modules`

Purpose

Return full module catalog.

Auth

Internal auth required.

Who can call

Platform Admin Backend
Auth Backend (optional)
internal jobs

Query params

None.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "modules": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "key": "basic",
        "name": "Core App",
        "type": "base",
        "description": "Core App / Basic product module",
        "isActive": true
      },
      {
        "id": "22222222-2222-2222-2222-222222222222",
        "key": "finance",
        "name": "Finance",
        "type": "addon",
        "description": "Finance module",
        "isActive": true
      }
    ]
  }
}

Errors

401 unauthorized
500 internal_error

6.2 `GET /internal/catalog/modules/{moduleId}`

Purpose

Return one module definition by id.

Auth

Internal auth required.

Who can call

Platform Admin Backend
Auth Backend (optional)
internal jobs

Path params

moduleId - required UUID

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "key": "finance",
    "name": "Finance",
    "type": "addon",
    "description": "Finance module",
    "isActive": true
  }
}

Errors

400 validation_error
401 unauthorized
404 not_found
500 internal_error

6.3 `GET /internal/catalog/packages`

Purpose

Return full package catalog.

Auth

Internal auth required.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "packages": [
      {
        "id": "33333333-3333-3333-3333-333333333333",
        "key": "basic",
        "name": "Basic",
        "description": "Basic subscription that enables Core App",
        "isActive": true,
        "priceMinor": 99.00,
        "currency": "USD",
        "billingInterval": "monthly",
        "taxCode": "digital_services",
        "taxInclusive": false,
        "trialDays": 14,
        "regionPricing": [],
        "modules": ["basic"]
      }
    ]
  }
}

Errors

401 unauthorized
500 internal_error

6.4 `GET /internal/catalog/packages/{packageId}`

Purpose

Return one package definition by id.

Auth

Internal auth required.

Path params

packageId - required UUID

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "id": "33333333-3333-3333-3333-333333333333",
    "key": "basic",
    "name": "Basic",
    "description": "Basic subscription that enables Core App",
    "isActive": true,
    "priceMinor": 99.00,
    "currency": "USD",
    "billingInterval": "monthly",
    "taxCode": "digital_services",
    "taxInclusive": false,
    "trialDays": 14,
    "regionPricing": [],
    "modules": ["basic"]
  }
}

Errors

400 validation_error
401 unauthorized
404 not_found
500 internal_error

6.5 `GET /internal/catalog/addons`

Purpose

Return full add-on catalog.

Auth

Internal auth required.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "addons": [
      {
        "id": "44444444-4444-4444-4444-444444444444",
        "key": "finance",
        "name": "Finance",
        "description": "Finance add-on",
        "isActive": true,
        "priceMinor": 49.00,
        "currency": "USD",
        "billingInterval": "monthly",
        "taxCode": "digital_services",
        "taxInclusive": false,
        "trialDays": 7,
        "regionPricing": [],
        "modules": ["finance"]
      },
      {
        "id": "55555555-5555-5555-5555-555555555555",
        "key": "market",
        "name": "Market",
        "description": "Market add-on",
        "isActive": true,
        "modules": ["market"]
      }
    ]
  }
}

Errors

401 unauthorized
500 internal_error

6.6 `GET /internal/catalog/addons/{addonId}`

Purpose

Return one add-on definition by id.

Auth

Internal auth required.

Path params

addonId - required UUID

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "id": "44444444-4444-4444-4444-444444444444",
    "key": "finance",
    "name": "Finance",
    "description": "Finance add-on",
    "isActive": true,
    "priceMinor": 49.00,
    "currency": "USD",
    "billingInterval": "monthly",
    "taxCode": "digital_services",
    "taxInclusive": false,
    "trialDays": 7,
    "regionPricing": [],
    "modules": ["finance"]
  }
}

Errors

400 validation_error
401 unauthorized
404 not_found
500 internal_error

7. Company read and entitlement endpoints

6.4A `GET /internal/companies`

Purpose

Return a paginated internal admin list of companies.

This route is intended for:

admin company pickers
platform-admin company overview screens
internal tools that need company master data without loading each company one by one

Returned data shape

Each row includes:

company → the full Core company master row
profile → the company profile row when it exists
addresses → all addresses for that company

This route does not include:

social links
documents
entitlements
subscription summary
history

Auth

Internal auth required.

Query parameters

Name	Type	Required	Behavior
`page`	integer	no	defaults to `1` when omitted or `< 1`
`limit`	integer	no	defaults to `20` when omitted or `< 1`; maximum `100`

Request body

No body.

Example request

GET /internal/companies?page=1&limit=20
X-Internal-API-Key: <secret>
Accept: application/json

Success — 200

{
  "success": true,
  "data": {
    "companies": [
      {
        "company": {
          "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
          "kisumCompanyId": "6800f4d9c1a2b3c4d5e6f789",
          "legalName": "Kisum Entertainment Group Pte Ltd",
          "displayName": "Kisum Entertainment Group",
          "status": "active",
          "createdSource": "internal",
          "billingProvider": "stripe",
          "billingCustomerId": "cus_123456789",
          "metadata": {
            "region": "SG"
          },
          "createdAt": "2026-04-18T10:00:00Z",
          "updatedAt": "2026-04-18T10:00:00Z"
        },
        "profile": {
          "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
          "slug": "kisum-entertainment",
          "logoUrl": "https://files.kisum.dev/companies/kisum-entertainment/logo.png",
          "website": "https://kisum.dev",
          "email": "hello@kisum.dev",
          "phone": "+65 6123 4567",
          "timezone": "Asia/Singapore",
          "industry": "Entertainment",
          "description": "Artist management and touring operations",
          "metadata": {
            "preferredLanguage": "en"
          }
        },
        "addresses": [
          {
            "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
            "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
            "type": "primary",
            "line1": "120 Orchard Road",
            "line2": "Level 15",
            "city": "Singapore",
            "state": "Singapore",
            "postalCode": "238888",
            "country": "Singapore",
            "isPrimary": true
          }
        ]
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Notes

ordering is newest-first by companies.created_at DESC
profile is omitted when no profile row exists
addresses is an empty array when no address rows exist
this is an admin list endpoint, not a full company bundle endpoint

6.4 `GET /internal/companies/{companyId}`

Purpose

Return the Core company master row only.

Auth

Internal auth required.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "kisumCompanyId": "6800f4d9c1a2b3c4d5e6f789",
    "legalName": "Kisum Entertainment Group Pte Ltd",
    "displayName": "Kisum Entertainment Group",
    "status": "active",
    "createdSource": "internal",
    "billingProvider": "stripe",
    "billingCustomerId": "cus_123456789",
    "metadata": {
      "region": "SG"
    },
    "createdAt": "2026-04-18T10:00:00Z",
    "updatedAt": "2026-04-18T10:00:00Z"
  }
}

6.5 `POST /internal/companies`

Purpose

Create the root company row and, optionally, the full nested company structure in one request.

Auth

Internal auth required.

Who can call

Platform Admin Backend
approved internal provisioning or migration jobs

Request body

legalName is required. All nested sections are optional.

{
  "legalName": "Kisum Entertainment Group Pte Ltd",
  "displayName": "Kisum Entertainment Group",
  "status": "active",
  "createdSource": "internal",
  "billingProvider": "stripe",
  "billingCustomerId": "cus_123456789",
  "metadata": {
    "region": "SG"
  },
  "profile": {
    "website": "https://group.kisum.dev",
    "email": "group@kisum.dev",
    "phone": "+65 6999 8888",
    "timezone": "Asia/Singapore",
    "industry": "Entertainment",
    "description": "Regional artist management and touring group",
    "metadata": {
      "preferredLanguage": "en"
    }
  },
  "addresses": [
    {
      "type": "primary",
      "line1": "120 Orchard Road",
      "line2": "Level 15",
      "city": "Singapore",
      "state": "Singapore",
      "postalCode": "238888",
      "country": "Singapore",
      "isPrimary": true
    }
  ],
  "socialLinks": [
    {
      "platform": "instagram",
      "label": "Official Instagram",
      "url": "https://instagram.com/kisumgroup"
    }
  ],
  "documents": [
    {
      "type": "business_registration",
      "name": "Business Registration Certificate",
      "storageKey": "companies/company-id/business-registration.pdf",
      "url": "https://files.kisum.dev/companies/company-id/business-registration.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 251004,
      "metadata": {
        "version": 1
      }
    }
  ]
}

Validation rules

legalName is required
id, if provided, must be a valid UUID
addresses[].line1 is required for every address
socialLinks[].platform and socialLinks[].url are required
documents[].type and documents[].name are required

Behavior

creates the companies row first
upserts profile into company_profiles when provided
inserts addresses into company_addresses
inserts socialLinks into company_social_links
inserts documents into company_documents
everything runs in one transaction

Success — 201

Response returns the full stored bundle:

{
  "success": true,
  "data": {
    "company": {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "legalName": "Kisum Entertainment Group Pte Ltd",
      "displayName": "Kisum Entertainment Group",
      "status": "active",
      "createdSource": "internal",
      "createdAt": "2026-04-18T10:00:00Z",
      "updatedAt": "2026-04-18T10:00:00Z"
    },
    "profile": {
      "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "website": "https://group.kisum.dev",
      "email": "group@kisum.dev",
      "phone": "+65 6999 8888",
      "timezone": "Asia/Singapore",
      "industry": "Entertainment",
      "description": "Regional artist management and touring group",
      "metadata": {
        "preferredLanguage": "en"
      },
      "createdAt": "2026-04-18T10:00:00Z",
      "updatedAt": "2026-04-18T10:00:00Z"
    },
    "addresses": [],
    "socialLinks": [],
    "documents": []
  }
}

6.6 `PATCH /internal/companies/{companyId}`

Purpose

Partially update the root company row and optionally synchronize nested company collections.

Auth

Internal auth required.

Who can call

Platform Admin Backend
approved internal provisioning tools

Request body

Any top-level field is optional.

{
  "displayName": "Kisum Entertainment Group",
  "profile": {
    "website": "https://group.kisum.dev",
    "email": "group@kisum.dev",
    "phone": "+65 6999 8888",
    "timezone": "Asia/Singapore",
    "industry": "Entertainment",
    "description": "Regional artist management and touring group",
    "metadata": {
      "preferredLanguage": "en"
    }
  },
  "addresses": [
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "type": "primary",
      "line1": "120 Orchard Road",
      "line2": "Level 15",
      "city": "Singapore",
      "state": "Singapore",
      "postalCode": "238888",
      "country": "Singapore",
      "isPrimary": true
    },
    {
      "type": "legal",
      "line1": "1 Marina Boulevard",
      "line2": "Suite 18-01",
      "city": "Singapore",
      "state": "Singapore",
      "postalCode": "018989",
      "country": "Singapore",
      "isPrimary": false
    }
  ]
}

Critical PATCH rules

omit a collection key to leave that collection unchanged
send addresses: [] to clear all addresses
send socialLinks: [] to clear all social links
send documents: [] to clear all documents
for nested collections:
- rows with id are updated
- rows without id are inserted
- rows omitted from a submitted collection are deleted

Safest frontend rule

only send the sections that the user actually edited
do not send empty arrays by accident
for single-item delete actions, subresource DELETE endpoints are still the clearest choice

Success — 200

Response returns the full stored bundle after patch:

{
  "success": true,
  "data": {
    "company": {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "legalName": "Kisum Entertainment Group Pte Ltd",
      "displayName": "Kisum Entertainment Group",
      "status": "active",
      "createdSource": "internal",
      "createdAt": "2026-04-18T10:00:00Z",
      "updatedAt": "2026-04-18T11:00:00Z"
    },
    "profile": {
      "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "website": "https://group.kisum.dev",
      "email": "group@kisum.dev",
      "phone": "+65 6999 8888",
      "timezone": "Asia/Singapore",
      "industry": "Entertainment",
      "description": "Regional artist management and touring group",
      "metadata": {
        "preferredLanguage": "en"
      },
      "createdAt": "2026-04-18T10:00:00Z",
      "updatedAt": "2026-04-18T11:00:00Z"
    },
    "addresses": [],
    "socialLinks": [],
    "documents": []
  }
}

6.7 `GET /internal/companies/{companyId}/profile`

Purpose

Return the current company profile row.

Auth

Internal auth required.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "slug": "kisum-entertainment-group",
    "logoUrl": "https://files.kisum.dev/companies/kisum-entertainment-group/logo.png",
    "website": "https://group.kisum.dev",
    "email": "group@kisum.dev",
    "phone": "+65 6999 8888",
    "timezone": "Asia/Singapore",
    "industry": "Entertainment",
    "description": "Regional artist management and touring group",
    "metadata": {
      "preferredLanguage": "en"
    },
    "createdAt": "2026-04-18T10:00:00Z",
    "updatedAt": "2026-04-18T11:00:00Z"
  }
}

6.8 `PUT /internal/companies/{companyId}/profile`

Purpose

Create or replace the single descriptive company profile row.

Auth

Internal auth required.

Request body

{
  "slug": "kisum-entertainment-group",
  "logoUrl": "https://files.kisum.dev/companies/kisum-entertainment-group/logo.png",
  "website": "https://group.kisum.dev",
  "email": "group@kisum.dev",
  "phone": "+65 6999 8888",
  "timezone": "Asia/Singapore",
  "industry": "Entertainment",
  "description": "Regional artist management and touring group",
  "metadata": {
    "preferredLanguage": "en"
  }
}

Behavior

inserts a new company_profiles row if none exists
updates the existing row if one already exists
does not affect addresses, social links, documents, subscriptions, or entitlements

Success — 200

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "slug": "kisum-entertainment-group",
    "logoUrl": "https://files.kisum.dev/companies/kisum-entertainment-group/logo.png",
    "website": "https://group.kisum.dev",
    "email": "group@kisum.dev",
    "phone": "+65 6999 8888",
    "timezone": "Asia/Singapore",
    "industry": "Entertainment",
    "description": "Regional artist management and touring group",
    "metadata": {
      "preferredLanguage": "en"
    },
    "createdAt": "2026-04-18T10:00:00Z",
    "updatedAt": "2026-04-18T11:00:00Z"
  }
}

6.9 `GET /internal/companies/{companyId}/addresses`

Purpose

List all company addresses.

Auth

Internal auth required.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "addresses": [
      {
        "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "type": "primary",
        "line1": "120 Orchard Road",
        "line2": "Level 15",
        "city": "Singapore",
        "state": "Singapore",
        "postalCode": "238888",
        "country": "Singapore",
        "isPrimary": true,
        "createdAt": "2026-04-18T10:00:00Z",
        "updatedAt": "2026-04-18T10:00:00Z"
      }
    ]
  }
}

6.10 `POST /internal/companies/{companyId}/addresses`

Purpose

Insert one address row under the company.

Request body

{
  "type": "primary",
  "line1": "120 Orchard Road",
  "line2": "Level 15",
  "city": "Singapore",
  "state": "Singapore",
  "postalCode": "238888",
  "country": "Singapore",
  "isPrimary": true
}

Success — 201

{
  "success": true,
  "data": {
    "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "type": "primary",
    "line1": "120 Orchard Road",
    "line2": "Level 15",
    "city": "Singapore",
    "state": "Singapore",
    "postalCode": "238888",
    "country": "Singapore",
    "isPrimary": true,
    "createdAt": "2026-04-18T10:00:00Z",
    "updatedAt": "2026-04-18T10:00:00Z"
  }
}

6.11 `PATCH /internal/companies/{companyId}/addresses/{addressId}`

Purpose

Update one company address row.

Request body

{
  "type": "billing",
  "line1": "80 Raffles Place",
  "line2": "Unit 20-01",
  "city": "Singapore",
  "state": "Singapore",
  "postalCode": "048624",
  "country": "Singapore",
  "isPrimary": false
}

Success — 200

{
  "success": true,
  "data": {
    "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "type": "billing",
    "line1": "80 Raffles Place",
    "line2": "Unit 20-01",
    "city": "Singapore",
    "state": "Singapore",
    "postalCode": "048624",
    "country": "Singapore",
    "isPrimary": false,
    "createdAt": "2026-04-18T10:00:00Z",
    "updatedAt": "2026-04-18T11:00:00Z"
  }
}

6.12 `DELETE /internal/companies/{companyId}/addresses/{addressId}`

Purpose

Delete one company address row.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "deleted": true,
    "addressId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
  }
}

6.13 `GET /internal/companies/{companyId}/social-links`

Purpose

List all company social links.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "socialLinks": [
      {
        "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
        "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "platform": "instagram",
        "label": "Official Instagram",
        "url": "https://instagram.com/kisumgroup",
        "createdAt": "2026-04-18T10:00:00Z"
      }
    ]
  }
}

6.14 `POST /internal/companies/{companyId}/social-links`

Purpose

Insert one company social-link row.

Request body

{
  "platform": "instagram",
  "label": "Official Instagram",
  "url": "https://instagram.com/kisumgroup"
}

Success — 201

{
  "success": true,
  "data": {
    "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "platform": "instagram",
    "label": "Official Instagram",
    "url": "https://instagram.com/kisumgroup",
    "createdAt": "2026-04-18T10:00:00Z"
  }
}

6.15 `DELETE /internal/companies/{companyId}/social-links/{socialLinkId}`

Purpose

Delete one company social link row.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "deleted": true,
    "socialLinkId": "cccccccc-cccc-cccc-cccc-cccccccccccc"
  }
}

6.16 `GET /internal/companies/{companyId}/documents`

Purpose

List all company documents.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
        "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "type": "business_registration",
        "name": "Business Registration Certificate",
        "storageKey": "companies/company-id/business-registration.pdf",
        "url": "https://files.kisum.dev/companies/company-id/business-registration.pdf",
        "mimeType": "application/pdf",
        "sizeBytes": 251004,
        "metadata": {
          "version": 1
        },
        "createdAt": "2026-04-18T10:00:00Z",
        "updatedAt": "2026-04-18T10:00:00Z"
      }
    ]
  }
}

6.17 `POST /internal/companies/{companyId}/documents`

Purpose

Insert one company document row.

Request body

{
  "type": "business_registration",
  "name": "Business Registration Certificate",
  "storageKey": "companies/company-id/business-registration.pdf",
  "url": "https://files.kisum.dev/companies/company-id/business-registration.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 251004,
  "metadata": {
    "version": 1
  }
}

Success — 201

{
  "success": true,
  "data": {
    "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "type": "business_registration",
    "name": "Business Registration Certificate",
    "storageKey": "companies/company-id/business-registration.pdf",
    "url": "https://files.kisum.dev/companies/company-id/business-registration.pdf",
    "mimeType": "application/pdf",
    "sizeBytes": 251004,
    "metadata": {
      "version": 1
    },
    "createdAt": "2026-04-18T10:00:00Z",
    "updatedAt": "2026-04-18T10:00:00Z"
  }
}

6.18 `DELETE /internal/companies/{companyId}/documents/{documentId}`

Purpose

Delete one company document row.

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "deleted": true,
    "documentId": "dddddddd-dddd-dddd-dddd-dddddddddddd"
  }
}

7.1 `GET /internal/companies/{companyId}/entitlements`

Purpose

Return the current normalized commercial entitlement state for one company.

Main consumer

Auth Backend, during /auth/me/access.

Runtime role of this endpoint

This endpoint returns company commercial entitlement state only.

It is intentionally designed for Auth to consume and merge with membership grants.

It must not be treated as a user-access endpoint by callers.

Auth

Internal auth required.

Who can call

Auth Backend
Platform Admin Backend
internal jobs

Path params

companyId — required UUID

Request body

No body.

Validation rules

companyId must be valid UUID
if company has no active Basic and no active add-ons, response still succeeds with empty entitlement state

Success — 200

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "hasBasic": false,
    "basePackage": null,
    "addons": [
      {
        "key": "finance",
        "status": "active",
        "startsAt": "2026-04-16T00:00:00Z",
        "endsAt": "2026-05-16T00:00:00Z"
      },
      {
        "key": "market",
        "status": "active",
        "startsAt": "2026-04-16T00:00:00Z",
        "endsAt": "2026-05-16T00:00:00Z"
      }
    ],
    "enabledModules": ["finance", "market"],
    "entitlementVersion": 7,
    "updatedAt": "2026-04-16T05:00:00Z"
  }
}

Example: Basic + Finance

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "hasBasic": true,
    "basePackage": "basic",
    "addons": [
      {
        "key": "finance",
        "status": "active",
        "startsAt": "2026-04-16T00:00:00Z",
        "endsAt": "2026-05-16T00:00:00Z"
      }
    ],
    "enabledModules": ["basic", "finance"],
    "entitlementVersion": 8,
    "updatedAt": "2026-04-16T05:00:00Z"
  }
}

Example: No entitlements

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "hasBasic": false,
    "basePackage": null,
    "addons": [],
    "enabledModules": [],
    "entitlementVersion": 1,
    "updatedAt": "2026-04-16T05:00:00Z"
  }
}

Errors

400 validation error

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "invalid companyId"
  }
}

401 unauthorized

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid internal credentials"
  }
}

404 not found

Use only if your system requires company existence to be pre-validated in Core.

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "company not found"
  }
}

500 internal error

{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "failed to load entitlements"
  }
}

7.2 `GET /internal/companies/{companyId}/subscription-summary`

Purpose

Return admin-friendly company subscription summary.

Auth

Internal auth required.

Who can call

Platform Admin Backend
internal jobs
Auth Backend (optional)

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "hasBasic": true,
    "basePackage": "basic",
    "items": [
      {
        "kind": "package",
        "id": "255db6d9-c9bc-4fff-a08f-b97f4906507e",
        "key": "basic",
        "name": "Basic",
        "description": "Basic subscription that enables the core application",
        "isActive": true,
        "status": "active",
        "startsAt": "2026-04-16T00:00:00Z",
        "endsAt": "2026-05-16T00:00:00Z",
        "priceMinor": 99.00,
        "currency": "USD",
        "billingInterval": "monthly",
        "taxCode": "digital_services",
        "taxInclusive": false,
        "trialDays": 14,
        "regionPricing": [
          {
            "region": "SG",
            "currency": "SGD",
            "priceMinor": 129.00
          }
        ],
        "entitlementKind": "package",
        "entitlementLabel": "Package"
      },
      {
        "kind": "addon",
        "id": "b8c37dfb-d154-408a-a7e8-fbfab9ff6a2c",
        "key": "finance",
        "name": "Finance",
        "description": "Finance add-on",
        "isActive": true,
        "status": "active",
        "startsAt": "2026-04-16T00:00:00Z",
        "endsAt": "2026-05-16T00:00:00Z",
        "priceMinor": 49.00,
        "currency": "USD",
        "billingInterval": "monthly",
        "taxCode": "digital_services",
        "taxInclusive": false,
        "trialDays": 7,
        "regionPricing": [],
        "entitlementKind": "addon",
        "entitlementLabel": "Add-on"
      },
      {
        "kind": "addon",
        "id": "d2f3e7f4-9159-4cfa-85a9-c3d9027d56a1",
        "key": "market",
        "name": "Market",
        "description": "Market add-on",
        "isActive": true,
        "status": "active",
        "startsAt": "2026-04-16T00:00:00Z",
        "endsAt": "2026-05-16T00:00:00Z",
        "priceMinor": 39.00,
        "currency": "USD",
        "billingInterval": "monthly",
        "taxCode": "digital_services",
        "taxInclusive": false,
        "trialDays": 0,
        "regionPricing": [],
        "entitlementKind": "addon",
        "entitlementLabel": "Add-on"
      }
    ],
    "entitlementVersion": 7
  }
}

Notes

items is the canonical admin-friendly array for UI rendering
one row is returned per active commercial assignment:
- one package row for the active base package, if present
- one addon row for each active add-on
each items[] row includes:
- catalog identity: id, key, name, description
- assignment state: status, startsAt, endsAt
- commercial values: priceMinor (decimal amount), currency, billingInterval, taxCode, taxInclusive, trialDays, regionPricing
a company may return only add-on rows and no package row when it has add-ons without an active base package

7.3 `GET /internal/companies/{companyId}/history`

Purpose

Return entitlement history for a company.

Auth

Internal auth required.

Who can call

Platform Admin Backend
internal audit/reporting jobs

Query params (optional)

limit
offset

Request body

No body.

Success — 200

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "history": [
      {
        "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
        "changeType": "addon_activated",
        "entityType": "addon",
        "entityKey": "finance",
        "previousStatus": "inactive",
        "newStatus": "active",
        "source": "platform_admin",
        "changedBy": "admin_user_uuid",
        "createdAt": "2026-04-16T05:00:00Z"
      }
    ]
  }
}

8. Catalog write endpoints

These are usually called by the Platform Admin Backend, not directly from UI.

8.1 `POST /internal/catalog/modules`

Purpose

Create a new module catalog entry.

Auth

Internal auth required.

Who can call

Platform Admin Backend only

Request body

{
  "key": "finance",
  "name": "Finance",
  "type": "addon",
  "description": "Finance module",
  "isActive": true
}

Validation rules

key required
key unique
key lowercase slug recommended
name required
type required and must be base or addon

Success — 201

{
  "success": true,
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "key": "finance",
    "name": "Finance",
    "type": "addon",
    "description": "Finance module",
    "isActive": true
  }
}

Conflict — 409

{
  "success": false,
  "error": {
    "code": "conflict",
    "message": "module key already exists"
  }
}

8.2 `PATCH /internal/catalog/modules/{moduleId}`

Purpose

Update existing module metadata.

Auth

Internal auth required.

Path params

moduleId — required UUID

Request body

All fields optional, but at least one required:

{
  "name": "Finance",
  "description": "Finance module updated",
  "isActive": true
}

Rules

key should be immutable after creation in first version
patch should update updated_at

Success — 200

{
  "success": true,
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "key": "finance",
    "name": "Finance",
    "type": "addon",
    "description": "Finance module updated",
    "isActive": true
  }
}

8.3 `DELETE /internal/catalog/modules/{moduleId}`

Purpose

Delete a module that is not linked to any package or add-on.

Path params

moduleId — required UUID

Success — 200

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "22222222-2222-2222-2222-222222222222"
  }
}

Errors

400 validation_error
401 unauthorized
404 not_found
409 conflict when the module is still linked to packages or add-ons
500 internal_error

8.4 `POST /internal/catalog/packages`

Purpose

Create a new package.

Auth

Internal auth required.

Request body

{
  "key": "basic",
  "name": "Basic",
  "description": "Basic subscription that enables Core App",
  "isActive": true,
  "priceMinor": 99.00,
  "currency": "USD",
  "billingInterval": "monthly",
  "taxCode": "digital_services",
  "taxInclusive": false,
  "trialDays": 14,
  "regionPricing": [
    {
      "region": "SG",
      "currency": "SGD",
      "priceMinor": 129.00
    }
  ],
  "moduleKeys": ["basic"]
}

Validation rules

key unique
priceMinor, currency, and billingInterval required; priceMinor is a decimal amount like 199.00
billingInterval must be monthly, quarterly, yearly, or one_time
trialDays must be >= 0
moduleKeys must all exist in modules
package may map to one or more modules

Success — 201

{
  "success": true,
  "data": {
    "id": "33333333-3333-3333-3333-333333333333",
    "key": "basic",
    "name": "Basic",
    "description": "Basic subscription that enables Core App",
    "isActive": true,
    "priceMinor": 99.00,
    "currency": "USD",
    "billingInterval": "monthly",
    "taxCode": "digital_services",
    "taxInclusive": false,
    "trialDays": 14,
    "regionPricing": [],
    "modules": ["basic"]
  }
}

8.5 `PATCH /internal/catalog/packages/{packageId}`

Purpose

Update package metadata and/or mapping.

Path params

packageId — UUID

Request body

{
  "name": "Basic",
  "description": "Updated Basic description",
  "isActive": true,
  "priceMinor": 119.00,
  "currency": "USD",
  "billingInterval": "yearly",
  "trialDays": 30,
  "moduleKeys": ["basic"]
}

Behavior

if moduleKeys is present, replace package mapping set with provided keys
mapping updates may require entitlement-version impact handling for active companies

Success — 200

{
  "success": true,
  "data": {
    "id": "33333333-3333-3333-3333-333333333333",
    "key": "basic",
    "name": "Basic",
    "description": "Updated Basic description",
    "isActive": true,
    "priceMinor": 119.00,
    "currency": "USD",
    "billingInterval": "yearly",
    "taxCode": "digital_services",
    "taxInclusive": false,
    "trialDays": 30,
    "regionPricing": [],
    "modules": ["basic"]
  }
}

8.6 `DELETE /internal/catalog/packages/{packageId}`

Purpose

Delete a package that is not assigned to any company subscription.

Path params

packageId — required UUID

Success — 200

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "33333333-3333-3333-3333-333333333333"
  }
}

Errors

400 validation_error
401 unauthorized
404 not_found
409 conflict when the package is assigned to companies
500 internal_error

8.7 `POST /internal/catalog/addons`

Purpose

Create a new add-on.

Request body

{
  "key": "finance",
  "name": "Finance",
  "description": "Finance add-on",
  "isActive": true,
  "priceMinor": 49.00,
  "currency": "USD",
  "billingInterval": "monthly",
  "taxCode": "digital_services",
  "taxInclusive": false,
  "trialDays": 7,
  "moduleKeys": ["finance"]
}

Validation rules

priceMinor, currency, and billingInterval required; priceMinor is a decimal amount like 199.00
add-on mappings may only include modules whose type is addon

Success — 201

{
  "success": true,
  "data": {
    "id": "44444444-4444-4444-4444-444444444444",
    "key": "finance",
    "name": "Finance",
    "description": "Finance add-on",
    "isActive": true,
    "priceMinor": 49.00,
    "currency": "USD",
    "billingInterval": "monthly",
    "taxCode": "digital_services",
    "taxInclusive": false,
    "trialDays": 7,
    "regionPricing": [],
    "modules": ["finance"]
  }
}

8.8 `PATCH /internal/catalog/addons/{addonId}`

Purpose

Update add-on metadata and/or mapping.

Path params

addonId — UUID

Request body

{
  "name": "Finance",
  "description": "Finance updated",
  "isActive": true,
  "priceMinor": 59.00,
  "currency": "USD",
  "billingInterval": "yearly",
  "moduleKeys": ["finance"]
}

Success — 200

{
  "success": true,
  "data": {
    "id": "44444444-4444-4444-4444-444444444444",
    "key": "finance",
    "name": "Finance",
    "description": "Finance updated",
    "isActive": true,
    "priceMinor": 59.00,
    "currency": "USD",
    "billingInterval": "yearly",
    "taxCode": "digital_services",
    "taxInclusive": false,
    "trialDays": 7,
    "regionPricing": [],
    "modules": ["finance"]
  }
}

8.9 `DELETE /internal/catalog/addons/{addonId}`

Purpose

Delete an add-on that is not assigned to any company.

Path params

addonId — required UUID

Success — 200

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "44444444-4444-4444-4444-444444444444"
  }
}

Errors

400 validation_error
401 unauthorized
404 not_found
409 conflict when the add-on is assigned to companies
500 internal_error

9. Company entitlement write endpoints

9.1 `POST /internal/companies/{companyId}/basic`

Purpose

Create or update Basic subscription state for a company.

Auth

Internal auth required.

Who can call

Platform Admin Backend
optional billing/reconciliation jobs

Path params

companyId — UUID

Request body

{
  "status": "active",
  "startsAt": "2026-04-16T00:00:00Z",
  "endsAt": "2026-05-16T00:00:00Z",
  "source": "platform_admin",
  "externalReference": "sub_123"
}

Valid status values

active
inactive
cancelled
expired
trial
paused

Behavior

resolve package basic
upsert company_subscriptions
bump entitlementVersion
write entitlement history
return normalized summary

Success — 200

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "hasBasic": true,
    "basePackage": "basic",
    "entitlementVersion": 8
  }
}

Example deactivation request

{
  "status": "inactive",
  "source": "platform_admin"
}

9.2 `POST /internal/companies/{companyId}/addons`

Purpose

Create or update add-on state for one company/add-on pair.

Auth

Internal auth required.

Who can call

Platform Admin Backend
optional billing/reconciliation jobs

Path params

companyId — UUID

Request body

{
  "addonKey": "finance",
  "status": "active",
  "startsAt": "2026-04-16T00:00:00Z",
  "endsAt": "2026-05-16T00:00:00Z",
  "source": "platform_admin",
  "externalReference": "addon_sub_123"
}

Behavior

resolve addon by addonKey
upsert company_addons
bump entitlementVersion
write entitlement history
return normalized addon result

Success — 200

{
  "success": true,
  "data": {
    "companyId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "addonKey": "finance",
    "status": "active",
    "entitlementVersion": 9
  }
}

Example deactivate addon

{
  "addonKey": "finance",
  "status": "inactive",
  "source": "platform_admin"
}

Validation errors

Missing addonKey

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "addonKey is required"
  }
}

Unknown addonKey

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "addon not found"
  }
}

10. Versioning and invalidation contract

10.1 Version source

Core returns entitlementVersion in all company entitlement responses.

10.2 Mandatory version bumps

Core must bump entitlementVersion when:

Basic activated
Basic deactivated
Basic expired
add-on activated
add-on deactivated
add-on expired
package mapping changed in a way affecting active companies
add-on mapping changed in a way affecting active companies
manual entitlement repair

10.3 Contract expectation for Auth

Auth will use:

access:{companyId}:{membershipId}:{accessVersion}:{entitlementVersion}

or equivalent cache strategy.

Core does not manage Auth cache directly via this API contract.
But Core must always return the correct current version.

11. Request/response behavior rules

11.1 Time format

All timestamps are ISO-8601 UTC strings, example:

2026-04-16T05:00:00Z

11.2 Nullability

basePackage may be null
startsAt / endsAt may be null
arrays should be empty arrays, not null, unless there is a strong reason otherwise

11.3 Normalization

Responses must be normalized and not leak DB implementation details.

Good

{
  "addons": [
    { "key": "finance", "status": "active" }
  ]
}

Avoid

{
  "addons": [
    { "addon_id": "uuid", "company_addon_status": "A" }
  ]
}

12. HTTP status map

Status	Meaning
200	Successful read/update
201	Successful creation
400	Validation error
401	Missing/invalid internal auth
403	Authenticated internal caller but not allowed
404	Resource not found
409	Conflict
500	Internal server error
503	Dependency not ready / service unavailable

13. Typical integration flows

13.1 Auth access aggregation flow

Frontend calls /auth/me/access
Auth loads user grants from Auth DB
Auth calls:
- GET /internal/companies/{companyId}/entitlements
Core returns normalized company entitlements
Auth merges:
- entitlements ∩ membership grants
Auth returns effective access to frontend

13.2 Platform Admin catalog flow

Platform Admin UI calls Admin Backend
Admin Backend validates platform-admin access
Admin Backend calls Core internal catalog write endpoint
Core writes DB rows and mapping rows
Core returns normalized object

13.3 Platform Admin subscription flow

Platform Admin UI calls Admin Backend
Admin Backend validates admin rights
Admin Backend calls POST /internal/companies/{companyId}/basic or /addons
Core updates state
Core bumps version
Auth cache becomes stale and must rebuild on next access resolution

14. Contract notes for QA

QA should validate at minimum:

GET /health
GET /ready
unauthorized internal call returns 401
module/package/addon reads return normalized arrays
company with no Basic but active addon returns valid entitlements
company with Basic + addon returns both in enabled modules
activating/deactivating Basic bumps entitlementVersion
activating/deactivating addon bumps entitlementVersion
patching catalog records preserves immutable keys
invalid UUID returns validation error
unknown addon/module/package returns not found where appropriate

15. Final summary

This contract defines how internal services interact with Platform Core.
Core exposes catalog APIs and company entitlement APIs.
Auth reads company entitlements from Core.
Platform Admin writes company commercial state into Core.
Core returns normalized enabled modules and entitlementVersion.
Core does not return user permissions, roles, or grants.
Frontend should not call Core directly for access decisions.
Business backends should not use Core as a user-authorization service.

16. Access model layers (REFERENCE — DO NOT IMPLEMENT HERE)

Platform Core participates in a 3-layer access model but only owns Level 1.

Level 1 — Company entitlements (OWNED BY CORE)

Defines what the company has purchased:

Basic
Finance
Market
Touring
Venue
AI

Source of truth: Platform Core DB

Level 2 — Membership module grants (OWNED BY AUTH)

Defines which modules a user can access. Core MUST NOT store or evaluate this.

Level 3 — Permissions (OWNED BY AUTH)

Defines actions inside modules. Core MUST NOT store or evaluate this.

Critical rule

Core returns entitlements ONLY
Core never computes user access

17. Relationship with Auth (STRICT)

Platform Core is a dependency of Auth.

Flow

Auth → Core → Auth → Frontend

Responsibilities

Core:

returns company entitlements
returns enabled modules
returns entitlementVersion

Auth:

merges entitlements with user grants
computes effective access
returns final access model

Forbidden usage

Core must NEVER:

return user-level access
validate permissions
validate roles
decide if a request is allowed

18. Effective access boundary

Core MUST NOT implement:

effective_access = entitlements ∩ grants

This logic belongs ONLY to Auth.

19. Delegation awareness (READ-ONLY CONTEXT)

Core is aware that delegation exists, but:

does not enforce delegation
does not validate delegation
does not store delegation rules

Delegation is owned by Auth.

20. Frontend & Backend interaction rules

Frontend

Frontend must NOT call Platform Core directly for access.

Allowed frontend calls:

Auth
Base backend
module backends
admin backend

Business backends

Business backends must NOT:

call Core for user access decisions
use Core as authorization service

They must rely on:

Auth → /auth/me/access

21. Final enforcement rule

Core = commercial truth
Auth = access truth
Backend = enforcement
Frontend = UX only

Backend Core API Contract (OpenAPI-Style)

Contract Specification for Platform Core Internal API

Company paths in this API

0. API overview

0.1 Public catalog routes (browser-facing, CORS-gated)

Runtime implementation note

0.0.2 Core email behavior

0.0.1 What the company sub-resource endpoints are for

PUT /internal/companies/{companyId}/profile

GET /internal/companies/{companyId}/business-units

POST /internal/companies/{companyId}/business-units

PATCH /internal/business-units/{businessUnitId}

POST /internal/companies/{companyId}/addresses

POST /internal/companies/{companyId}/social-links

POST /internal/companies/{companyId}/documents

0.1 Runtime position in the platform

Main runtime rule

Important implication

0.2 Request ownership and primary callers

Frontend should not call Platform Core directly

Primary caller

Secondary callers

Non-primary callers

Clean runtime pattern

0.3 Naming clarification

1. Base URL and exposure model

1.1 Recommended base URL

1.2 Exposure model

Integration note

2. Content type and response conventions

2.1 Request content type

2.2 Success envelope

2.3 Error envelope

2.4 Standard error codes

3. Internal authentication contract

3.1 Required authentication

3.2 Required behavior

Example error

4. Common object schemas

4.1 Module object

Fields

4.2 Package object

Fields

4.3 Add-on object

4.4 Company add-on summary

4.5 Company entitlement object

4.6 Entitlement history object

5. Health endpoints

5.1 GET /health

Purpose

Auth

Request body

Response — 200

5.2 GET /ready

Purpose

Readiness checks

Request body

Success — 200

Failure — 503

6. Catalog read endpoints

6.1 GET /internal/catalog/modules

Purpose

Auth

Who can call

Query params

Request body

Success — 200

Errors

6.2 GET /internal/catalog/modules/{moduleId}

Purpose

Auth

Who can call

Path params

Request body

Success — 200

Errors

6.3 GET /internal/catalog/packages

Purpose

Auth

Request body

`PUT /internal/companies/{companyId}/profile`

`GET /internal/companies/{companyId}/business-units`

`POST /internal/companies/{companyId}/business-units`

`PATCH /internal/business-units/{businessUnitId}`

`POST /internal/companies/{companyId}/addresses`

`POST /internal/companies/{companyId}/social-links`

`POST /internal/companies/{companyId}/documents`

5.1 `GET /health`

5.2 `GET /ready`

6.1 `GET /internal/catalog/modules`

6.2 `GET /internal/catalog/modules/{moduleId}`

6.3 `GET /internal/catalog/packages`

6.4 `GET /internal/catalog/packages/{packageId}`

6.5 `GET /internal/catalog/addons`

6.6 `GET /internal/catalog/addons/{addonId}`

6.4A `GET /internal/companies`

6.4 `GET /internal/companies/{companyId}`

6.5 `POST /internal/companies`

6.6 `PATCH /internal/companies/{companyId}`

6.7 `GET /internal/companies/{companyId}/profile`

6.8 `PUT /internal/companies/{companyId}/profile`

6.9 `GET /internal/companies/{companyId}/addresses`