Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Codefied-CodePix/Karokar-backend/llms.txt

Use this file to discover all available pages before exploring further.

The Administration API provides the platform-level controls that govern which organisations are permitted to operate within the KaroKar marketplace. Before a vendor can list vehicles or a corporate organisation can place bookings, a platform administrator must approve the organisation through this workflow. Each decision — approval, rejection, or suspension — is recorded as an immutable OrganizationApproval record and broadcasts a domain event to notify the rest of the platform. All three endpoints share the same organization.approve permission, which is held exclusively by users with the PLATFORM_ADMIN role.
All endpoints in this group require the organization.approve permission. Only users with the PLATFORM_ADMIN role are granted this permission. Calls from any other role will receive a 403 Forbidden response.
All requests require an Authorization: Bearer <token> header. The authenticated user’s userId and organizationId are extracted from the token and recorded as the reviewer on every approval record.

​
ApprovalStatus Values

Every OrganizationApproval record carries one of the following statuses:
StatusMeaning
PENDINGThe organisation has been submitted for review but no decision has been made.
APPROVEDThe organisation has been approved and may operate on the platform.
REJECTEDThe organisation’s application was denied.
REVOKEDA previously approved or active organisation has had its access revoked (written by the suspend workflow).

​
OrganizationApproval Entity Fields

All three endpoints return an OrganizationApproval object with the following fields:
​
id
string (UUID)
Unique identifier for this approval record, auto-generated.
​
organizationId
string (UUID)
UUID of the organisation being reviewed.
​
status
ApprovalStatus
The outcome of the review action. See ApprovalStatus Values above.
​
reviewedBy
string (UUID) | null
UUID of the platform admin user who performed the review, or null if not yet reviewed.
​
reviewedAt
string (ISO 8601) | null
Timestamp when the review was completed, or null if not yet reviewed.
​
notes
string | null
Optional free-text notes recorded by the reviewer, or null if none were provided.
​
createdAt
string (ISO 8601)
Timestamp when the approval record was created.

​
POST /admin/organizations/:id/approve

Approve an organisation, granting it the right to operate on the KaroKar platform. Creates an OrganizationApproval record with APPROVED status, records the reviewing admin, and emits an OrganizationApproved domain event. Required permission: organization.approve

​
Path Parameters

​
id
string (UUID)
required
UUID of the organisation to approve.

​
Request Body

​
notes
string
Optional free-text notes from the reviewer, e.g. conditions of approval or references to supporting documents.

​
Response

Returns the newly created OrganizationApproval record.

​
Errors

HTTPCondition
403Caller lacks organization.approve permission (non-PLATFORM_ADMIN user)
501Service method not yet fully implemented

​
Example

curl -X POST http://localhost:3000/admin/organizations/b2c3d4e5-f6a7-8901-bcde-f12345678901/approve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"notes": "All documents verified. Approved for full platform access."}'

{
  "id": "f7a8b9c0-d1e2-3456-abcd-567890123456",
  "organizationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "APPROVED",
  "reviewedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reviewedAt": "2025-08-20T14:00:00.000Z",
  "notes": "All documents verified. Approved for full platform access.",
  "createdAt": "2025-08-20T14:00:00.000Z"
}

​
POST /admin/organizations/:id/reject

Reject an organisation’s application, preventing it from operating on the platform. Creates an OrganizationApproval record with REJECTED status and emits an OrganizationRejected domain event. Required permission: organization.approve

​
Path Parameters

​
id
string (UUID)
required
UUID of the organisation to reject.

​
Request Body

​
notes
string
Optional free-text notes from the reviewer. It is strongly recommended to include a reason for rejection so the organisation can address the issue and reapply.

​
Response

Returns the newly created OrganizationApproval record with status: "REJECTED".

​
Errors

HTTPCondition
403Caller lacks organization.approve permission
501Service method not yet fully implemented

​
Example

curl -X POST http://localhost:3000/admin/organizations/b2c3d4e5-f6a7-8901-bcde-f12345678901/reject \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Incomplete insurance documentation. Please resubmit with valid certificates."}'

{
  "id": "a8b9c0d1-e2f3-4567-bcde-678901234567",
  "organizationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "REJECTED",
  "reviewedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reviewedAt": "2025-08-20T14:05:00.000Z",
  "notes": "Incomplete insurance documentation. Please resubmit with valid certificates.",
  "createdAt": "2025-08-20T14:05:00.000Z"
}

​
POST /admin/organizations/:id/suspend

Suspend an organisation that is currently active on the platform, immediately halting its ability to create or accept bookings. Creates an OrganizationApproval record capturing the suspension, and emits an OrganizationSuspended domain event. Required permission: organization.approve
Suspending an organisation may affect in-flight bookings. Ensure any active bookings are handled appropriately before suspending a vendor or corporate organisation.

​
Path Parameters

​
id
string (UUID)
required
UUID of the organisation to suspend.

​
Request Body

​
notes
string
Optional free-text notes from the reviewer. Strongly recommended — document the reason for suspension for audit purposes.

​
Response

Returns the newly created OrganizationApproval record reflecting the suspension decision.

​
Errors

HTTPCondition
403Caller lacks organization.approve permission
501Service method not yet fully implemented

​
Example

curl -X POST http://localhost:3000/admin/organizations/b2c3d4e5-f6a7-8901-bcde-f12345678901/suspend \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Suspended pending investigation into compliance breach reported on 2025-08-19."}'

{
  "id": "b9c0d1e2-f3a4-5678-cdef-789012345678",
  "organizationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "REVOKED",
  "reviewedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reviewedAt": "2025-08-20T14:10:00.000Z",
  "notes": "Suspended pending investigation into compliance breach reported on 2025-08-19.",
  "createdAt": "2025-08-20T14:10:00.000Z"
}

​
Audit Trail

Every call to approve, reject, or suspend an organisation creates a new OrganizationApproval row rather than mutating an existing one. This means the organization_approvals table functions as an append-only audit log. You can reconstruct the full decision history for any organisation by querying all rows where organizationId matches the target.
When building admin dashboards, sort OrganizationApproval records by createdAt descending to display the most recent decision first.

Build docs developers (and LLMs) love

Get started for freeTalk to us