Platform Admin Service — API Contracts

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 05 API Design

Base URL: https://api.ghasi-ehealth.{tld} Auth: Bearer JWT (RS256) except internal routes.

1. Platform configuration (Super Admin)

Method	Path	Scope	Summary
GET	/api/v1/admin/platform-config	SUPER_ADMIN	List all config entries
POST	/api/v1/admin/platform-config	SUPER_ADMIN	Upsert config entry
GET	/api/v1/admin/platform-config/:key/history	SUPER_ADMIN	Change history (cursor-paginated)
DELETE	/api/v1/admin/platform-config/:id	SUPER_ADMIN	Archive config entry

POST /api/v1/admin/platform-config — request:

{
  "key": "global.session_idle_minutes",
  "value": "30",
  "scope": "PLATFORM",
  "tenantId": null,
  "description": "Global session idle timeout"
}

200 response:

{
  "key": "global.session_idle_minutes",
  "value": "30",
  "scope": "PLATFORM",
  "tenantId": null,
  "isArchived": false,
  "updatedAt": "2026-04-18T10:00:00Z"
}

Errors: 400 ADM_CONFIG_KEY_UNKNOWN, 400 ADM_CONFIG_VALUE_INVALID.

GET /api/v1/admin/platform-config/:key/history — response:

{
  "data": [
    {
      "changedAt": "2026-04-18T09:00:00Z",
      "changedBy": "usr_01H...",
      "oldValue": "20",
      "newValue": "30",
      "scope": "PLATFORM"
    }
  ],
  "nextCursor": "cur_01H..."
}

2. Feature flags (Super Admin)

Method	Path	Scope	Summary
GET	/api/v1/admin/flags	SUPER_ADMIN	List all flags
GET	/api/v1/admin/flags/:key	SUPER_ADMIN	Get flag details
POST	/api/v1/admin/flags	SUPER_ADMIN	Create flag
PATCH	/api/v1/admin/flags/:key	SUPER_ADMIN	Update description / defaultEnabled
DELETE	/api/v1/admin/flags/:key	SUPER_ADMIN	Archive flag
POST	/api/v1/admin/flags/:key/tenant-overrides	SUPER_ADMIN	Set tenant override
DELETE	/api/v1/admin/flags/:key/tenant-overrides/:tenantId	SUPER_ADMIN	Remove tenant override

POST /api/v1/admin/flags — request:

{
  "key": "feature.telehealth_beta",
  "description": "Enables telehealth video call feature for early adopters",
  "defaultEnabled": false
}

POST /admin/flags/:key/tenant-overrides — request:

{ "tenantId": "ten_01H...", "enabled": true }

Errors: 404 ADM_FLAG_NOT_FOUND, 409 ADM_FLAG_KEY_DUPLICATE, 422 ADM_FLAG_ARCHIVED.

3. Feature flags (Tenant Admin)

Method	Path	Scope	Summary
GET	/api/v1/platform/flags	TENANT_ADMIN	List flags with tenant-resolved state
GET	/api/v1/platform/flags/:key/evaluate	JWT	Evaluate flag for caller's tenant context

GET /platform/flags/:key/evaluate — response:

{ "key": "feature.telehealth_beta", "enabled": true, "reason": "tenant_override_enabled" }

4. Platform health

Method	Path	Scope	Summary
GET	/api/v1/admin/health/aggregate	SUPER_ADMIN or service	Aggregate health summary

GET /admin/health/aggregate — response:

{
  "overall": "degraded",
  "services": [
    { "serviceId": "identity-service", "status": "healthy", "lastChecked": "2026-04-18T10:00:00Z" },
    { "serviceId": "laboratory-service", "status": "unhealthy", "lastChecked": "2026-04-18T09:55:00Z" }
  ],
  "cachedAt": "2026-04-18T10:00:05Z"
}

Cache TTL: 10 s.

5. Internal routes (cluster-only, IP-restricted)

Method	Path	Summary
GET	/internal/admin/flags/:key/evaluate	Flag evaluation for services (p95 ≤ 120 ms)
GET	/internal/admin/flags/bootstrap	All flag decisions for tenant (used at service startup)
GET	/internal/admin/config/:key	Single config value lookup
POST	/internal/admin/health/sources	Register health source

GET /internal/admin/flags/:key/evaluate?tenantId=ten_01H...

{ "key": "feature.telehealth_beta", "enabled": true, "reason": "tenant_override_enabled" }

6. Pagination and rate limits

• History endpoint: cursor-based pagination (cursor, limit max 100).
• Flags and config list: offset pagination (page, pageSize max 100).
• Rate limits (Kong): Super Admin write endpoints 60/min; internal evaluate 1000/min/service.

7. Compatibility routes (M1 — legacy transition)

During the M0→M1 transition window, legacy /api/platform/* paths are proxied to /api/v1/admin/* routes via Kong route compatibility policy. Deprecated at M2; removed at M3.