Admin Dashboard — API Contracts

Status: populated Owner: Platform Engineering (Frontend) Last updated: 2026-04-18

1. Overview

The admin-dashboard has no external API. This document covers:

1. Next.js Route Handlers (BFF endpoints) called by client components.
2. Backend API endpoints consumed by server components and route handlers.

All backend calls use Authorization: Bearer <admin-platform-jwt> through Kong admin routes.

2. Next.js Route Handlers (BFF Layer)

POST /api/auth/logout

Clears __admin_session and __admin_refresh cookies; redirects to /login.

POST /api/auth/refresh

Proxies POST /v1/auth/refresh. Rotates session cookie.

GET /api/metrics

Aggregates data from analytics-service. Called by client-side polling every 30 seconds. Returns combined MetricsSummary + ThroughputPoint[] + DeliveryBreakdown + OperatorSummaryRow[].

POST /api/operators

Proxies POST /v1/internal/operators to operator-management-service.

PUT /api/operators/[operatorId]

Proxies PUT /v1/internal/operators/{operatorId}.

DELETE /api/operators/[operatorId]

Proxies DELETE /v1/internal/operators/{operatorId}.

POST /api/routing-rules

Proxies POST /v1/internal/routing/rules.

PUT /api/routing-rules/[ruleId]

Proxies PUT /v1/internal/routing/rules/{ruleId}.

DELETE /api/routing-rules/[ruleId]

Proxies DELETE /v1/internal/routing/rules/{ruleId}.

PUT /api/users/[userId]/status

Proxies PUT /v1/internal/users/{userId}/status — suspend / reactivate user.

DELETE /api/users/[userId]

Proxies DELETE /v1/internal/users/{userId}.

3. Backend Endpoints Consumed

Auth Service (Internal Routes)

Method	Path	Used on page	Purpose
GET	/v1/internal/auth/me	All pages (server)	Verify admin claim
POST	/v1/auth/refresh	Middleware	Rotate JWT
GET	/v1/internal/users	/users	List platform users
POST	/v1/internal/users	/users	Create user
PUT	/v1/internal/users/{userId}/status	/users	Suspend / reactivate
DELETE	/v1/internal/users/{userId}	/users	Delete user

Analytics Service

Method	Path	Used on page	Purpose
GET	/v1/internal/analytics/summary	/dashboard	24h KPI metrics
GET	/v1/internal/analytics/throughput?range=24h&interval=1h	/dashboard	Hourly throughput chart data
GET	/v1/internal/analytics/delivery-breakdown	/dashboard	Delivery status pie chart data
GET	/v1/internal/analytics/top-operators?limit=5	/dashboard	Top-5 operators table

Operator Management Service

Method	Path	Used on page	Purpose
GET	/v1/internal/operators	/operators	List all SMPP operators
GET	/v1/internal/operators/{operatorId}	/operators detail	Operator detail
POST	/v1/internal/operators	/operators	Create operator
PUT	/v1/internal/operators/{operatorId}	/operators	Update operator config
DELETE	/v1/internal/operators/{operatorId}	/operators	Delete operator
GET	/v1/internal/operators/{operatorId}/health	/operators	Live connection state

Routing Engine

Method	Path	Used on page	Purpose
GET	/v1/internal/routing/rules	/routing	List routing rules
POST	/v1/internal/routing/rules	/routing	Create routing rule
PUT	/v1/internal/routing/rules/{ruleId}	/routing	Update rule
DELETE	/v1/internal/routing/rules/{ruleId}	/routing	Delete rule
POST	/v1/internal/routing/rules/reorder	/routing	Reorder priority

Message Store / SMS Orchestrator

Method	Path	Used on page	Purpose
GET	/v1/internal/messages	/messages	Cross-tenant message log
GET	/v1/internal/messages/{messageId}	/messages detail	Full message detail

Query params for GET /v1/internal/messages:

Param	Type	Description
tenantId	string	Filter by tenant
accountId	string	Filter by account
from	string	Filter by sender
to	string	Filter by recipient
status	string	Delivery status
operatorId	string	Filter by operator
startDate	ISO8601
endDate	ISO8601
page	integer
limit	integer	Max 100

Billing Service

Method	Path	Used on page	Purpose
GET	/v1/internal/billing/invoices	/billing	All tenant invoices
GET	/v1/internal/billing/invoices/{invoiceId}	/billing	Invoice detail
GET	/v1/internal/billing/pricing	/billing	Current pricing config
PUT	/v1/internal/billing/pricing	/billing	Update pricing

System Health

Method	Path	Used on page	Purpose
GET	/v1/internal/health/services	/health	Aggregated service health
GET	/v1/internal/health/services/{serviceName}	/health	Single service health

4. Error Handling

HTTP Status	Dashboard behaviour
401	Attempt refresh; if fails, redirect to /login?reason=session_expired
403	Show "Insufficient permissions" toast; log to Sentry
429	Toast: "Rate limit exceeded"
5xx	Toast: "Backend error"; alert details logged to Sentry