Kopano Labs
Dashboard
Foundations

Introduction & Base URL

Welcome to the Kopano Labs clinical documentation. Our API is architected for high-concurrency environments requiring extreme precision in availability and settlement orchestration.

Development Base URL

https://api.kopanolabs.com/v2
Security Protocol

Unified Auth Flow

Kopano Labs leverages NextAuth.js for session management. All API requests must include a JWT or Bearer Token in the authorization header.

🔒

Session Validation

Tokens are validated against our internal identity provider in real-time.

Endpoint DetailsPOST
/auth/session/refresh

Extends the current user session and returns a fresh JWT.

Authentication Response
{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5...",
    "expires_at": "2026-08-24T12:08:002",
    "user": {
      "id": "user_98234",
      "scope": "read:availability write:payments"
    }
  }
}
Performance Engine

Real-Time Availability Engine

GET/api/availability

Query high-frequency availability slots across distributed global providers with sub-50ms latency.

Query Parameters

provider_idUUID (Required)

The unique identifier of the service provider.

timestampISO 8601

The start window for slot searching.

bufferInteger

Safety padding in minutes.

✏️

Low Latency Guarantee

Our engine uses localized caching nodes to ensure that the /availability endpoint maintains consistent response times during peak demand.

Avg. Response Time

43ms

System Visualization

Data Flow Protocol

An architectural deep-dive into the Kopano Labs ecosystem. Mapping the journey of a request from the edge to the database and external integration points.

Request Initiation

TanStack Start leverages Server Components for high-performance data fetching at the edge. Initial payloads are rendered server-side to minimize client-side hydrations.

Entry PointGET

App Router (v15)

  • • Dynamic Rendering
  • • Streaming Suspense
↓
Security Layer

NextAuth.js Integration

JWTOAuth 2.0Session Guard

Auth Middleware

Every incoming request is intercepted by the edge middleware. User sessions are verified against the persistence layer before reaching any sensitive API routes.

↓
Logic LayerServer Side

Server Actions

The orchestration engine. Directly mutates data without creating secondary API endpoints, ensuring type-safety from DB to UI.

Zod Validation

Runtime type checking of payloads.

Revalidation

Triggers revalidatePath() for UI sync.

↓
Persistence Layer

MongoDB Atlas

Region Cluster

Cape Town (af-south-1)

Automated sharding and global replication ensuring <50ms latency for African nodes. Multi-cloud backup protocol enabled.

Third Party Integrations

Payment Webhooks

Paystack Event HandlersActive
Yoco Event HandlersActive
Ozow Event HandlersActive
Financial Layer

Modular Payment Wrapper

One integration, multiple gateways. Kopano Labs abstracts the complexities of Paystack, Yoco, and Ozow into a single, predictable interface.

Webhook Logic

Webhooks are dispatched with an X-Kopano-Signature. Always verify this signature before processing financial state changes.

🏦
💳
📱
Webhook Payload Example
{
  "event": "payment.captured",
  "gateway": "yoco",
  "amount": 550.00,
  "currency": "ZAR",
  "meta": {
    "reference": "KP-0832",
    "customer": "jane_doe@test.com"
  }
}
Diagnostics

Error Codes

400_INVALID_PARAMS

The request body contains schema errors.

401_UNAUTHORIZED

Bearer token is missing or expired.

429_RATE_LIMIT

Request quota exceeded.

503_GATEWAY_TIMEOUT

Downstream payment provider failure.

Throttling

Rate Limiting

To preserve system integrity, Kopano Labs enforces sliding-window rate limits based on your tier.

Standard Tier

Default for new keys

1kreq/min

Enterprise Tier

High-volume settlement

50k+req/min