Backend Base Integration Guide

KISUM PLATFORM — BASE BACKEND INTEGRATION GUIDE

Version: 1.0.0
Audience: junior frontend developers, junior backend developers, QA, partners
Status: integration guide

---

1. Purpose of this document

This document explains how to call the Base Backend correctly in the new architecture.

It covers:

• how auth works from the caller point of view
• how to send Authorization
• how to send x-org
• what sequence to follow
• how to think about errors
• working request examples
• what not to do

This is the “how to integrate” document.

For full architecture, see:

• KISUM_BASE_ARCHITECTURE.md

For the API catalog, see:

• KISUM_BASE_API.md

---

2. Basic integration idea

You do not log in through Base Backend.

You:

1. authenticate through Auth Backend
2. obtain a JWT
3. choose the active company
4. call Base Backend with:
   • Authorization: Bearer <JWT>
   • x-org: <COMPANY_ID>

Base Backend then:

• validates the JWT
• validates x-org
• resolves effective access from Auth
• checks basic module
• checks permission
• allows or denies the route

---

3. Required headers

Every protected request must include:

Authorization: Bearer <JWT_FROM_AUTH_SERVICE>
x-org: <COMPANY_ID>
Content-Type: application/json

3.1 Authorization

Must be a token issued by Auth.

3.2 x-org

Must be the active company ID for the request.

3.3 Content-Type

Usually application/json, unless the route uses uploads.

---

4. End-to-end caller flow

Step 1 — Authenticate with Auth Backend

The user signs in through Auth, not Base.

Result:

• JWT token
• authenticated user session

Step 2 — Resolve who the user is

Caller can use Auth-side identity endpoints as needed.

Step 3 — Choose active company

The UI or caller determines the current company context.

That value is then sent in:

x-org: <COMPANY_ID>

Step 4 — Call Base Backend

Send the business request with:

• JWT
• x-org

Step 5 — Base enforces access

Base validates:

• JWT
• x-org
• effective access from Auth
• basic module
• permission

---

5. Example request flow

5.1 Example: list events

Request

curl -X GET 'http://localhost:3099/api/events?type=all&page=1&limit=20'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'

What must happen

• token valid
• company exists in user access scope
• basic module enabled
• user has event view permission

Typical outcome

• success → 200
• bad token → 401
• bad company → 400 or 403
• no access → 403
• access resolution unavailable → 503

---

6. Common request patterns

6.1 GET

curl -X GET 'http://localhost:3099/api/artists'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'

6.2 POST JSON

curl -X POST 'http://localhost:3099/api/agencies'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'   -H 'Content-Type: application/json'   -d '{
    "key": "agency-001",
    "name": "Example Agency"
  }'

6.3 PUT JSON

curl -X PUT 'http://localhost:3099/api/agencies/{id}'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'   -H 'Content-Type: application/json'   -d '{
    "name": "Updated Agency Name"
  }'

6.4 DELETE

curl -X DELETE 'http://localhost:3099/api/agencies/{id}'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'

6.5 Multipart upload

curl -X POST 'http://localhost:3099/api/files/upload'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'   -F 'file=@example.pdf'

---

7. What juniors must remember

7.1 Do not log in through Base

Base is not the login service.

7.2 Do not omit x-org

If the route is tenant-scoped, x-org is required.

7.3 Do not guess company

The UI or calling layer must know the active company and send it explicitly.

7.4 Do not trust frontend UI

Just because a button is visible or hidden does not mean the backend will allow the route.

7.5 Do not call deprecated groups

Do not use:

• Auth
• Users
• Company Users
• Invitations
• Teams
• Packages
• Permissions
• Role
• Subscription

Those moved to Auth/Core.

---

8. Error-handling guide

8.1 400 Bad Request

Usually means:

• missing x-org
• malformed x-org
• bad request payload

8.2 401 Unauthorized

Usually means:

• missing token
• invalid token
• expired token
• token rejected during validation

8.3 403 Forbidden

Usually means:

• membership not valid for x-org
• basic module missing
• permission missing

8.4 503 Service Unavailable

Usually means:

• Base could not resolve effective access from Auth
• Auth service unavailable
• network failure / timeout between services

8.5 Important rule

503 must not become temporary access.
The request must fail closed.

---

9. Integration anti-patterns

Do not do any of the following:

• call /auth/* on Base
• use Base as the source of identity
• use Base as the source of package/subscription truth
• infer access from the JWT alone
• assume company from frontend state without sending x-org
• silently retry with a different company
• bypass permission checks because a user is “probably admin”

---

10. Example frontend flow

A typical frontend flow should look like this:

1. User signs in with Auth
2. Frontend stores current JWT securely
3. Frontend gets or already knows active company
4. Frontend calls Base with JWT + x-org
5. If route denied:
   • show proper error
   • do not guess fallback
6. If 503:
   • show service unavailable / retry flow
   • do not fake access

---

11. Example backend-to-backend flow

If another internal backend calls Base on behalf of a user:

1. obtain or forward a valid Auth-issued JWT
2. send explicit x-org
3. call Base route
4. respect 401 / 403 / 503
5. do not add local bypass logic

---

12. Permission mapping examples

Examples of route-level access expectations:

• GET /dashboard → basic.dashboard.view
• GET /artists → basic.artist.view
• POST /artists → basic.artist.create
• PUT /artists/{id} → basic.artist.edit
• DELETE /artists/{id} → basic.artist.delete
• GET /events → basic.event.view
• POST /events → basic.event.create
• PUT /events/{id} → basic.event.edit
• DELETE /events/{id} → basic.event.delete
• GET /vendors → basic.vendor.view
• POST /vendors → basic.vendor.create
• GET /venues → basic.venue.view

These examples are helpful for integration teams even if the exact permission map is maintained elsewhere.

---

13. Active route families commonly used by integrations

Integrations will most often use:

• Agencies
• Agreements
• Ai
• Approval
• Artists
• Avails
• Companies (business metadata only)
• Dashboard
• Events
• Event Expense
• Event Expense - Approval
• Event Income
• Event Ticket
• Files
• Notifications
• Offer
• Tasks
• Vendors
• Venues
• Xero

For full route group listing, see:

• KISUM_BASE_API.md

---

14. Debugging checklist

If a request fails:

Check 1

Is the token present?

Check 2

Is the token issued by Auth and still valid?

Check 3

Is x-org present?

Check 4

Is x-org the intended company?

Check 5

Does the user belong to that company?

Check 6

Does the user have basic module?

Check 7

Does the user have the specific basic.* permission?

Check 8

Is Auth reachable for effective access resolution?

---

15. Final practical rule

To call Base successfully, always think:

Auth first
Company context second
Base business route third

If any of those are wrong, the request should fail.