[Proposal] Application-Level Subscriptions for REST APIs in the API Platform

[CrowleyRajapakse]

Problem Statement

Currently, REST APIs deployed in the API Platform are not associated with specific Applications. Although access tokens are issued per Application, the gateway’s token validation flow does not verify whether the Application is actually subscribed to the invoked API.

As a result, any token with a valid issuer can successfully pass validation and invoke API resources, even if the originating Application is not subscribed to that API.

Proposed Solution

Introduce Application-level subscription validation for REST APIs in the API Platform.

• Add an API-level policy to enable subscription validation for a given API and publish it to the Policy Hub.
• Introduce Application and Subscription database tables in both the platform-api and gateway-controller databases.
• Implement the /rest-apis/{apiId}/subscriptions CRUD APIs in platform-api to manage subscriptions and persist subscription data.
• Implement the /apis/{apiId}/subscriptions CRUD APIs and the required WebSocket resources in gateway-controller to manage subscriptions and synchronize subscription data.
• Implement subscription validation logic in the gateway (policy engine) to ensure requests are authorized only if the calling Application is subscribed to the target API.

[CrowleyRajapakse]

Application-Level Subscriptions for REST APIs — Implementation Plan

1. Executive Summary

Problem: REST APIs in the API Platform are not tied to Applications. Token validation only checks issuer/signature; it does not verify that the calling Application is subscribed to the invoked API. Any valid token can call any API.

Solution: Introduce Application and Subscription entities, CRUD APIs in platform-api and gateway-controller, WebSocket sync of subscription data to gateways, and subscription validation in the gateway policy engine so requests are allowed only when the Application (identified from the token) is subscribed to the target API.

---

2. Current State (Findings from Codebase)

2.1 Platform-API

• REST APIs: rest_apis table (uuid, description, project_uuid, configuration, etc.; uuid FK to artifacts). Routes: /api/v1/rest-apis, /api/v1/rest-apis/{apiId}, plus gateways, api-keys, deployments, devportals, etc.
• No Application or Subscription tables. Tokens are issued per application (STS) but platform does not store applications or API–application links.
• WebSocket: Platform broadcasts api.deployed, api.undeployed, api.deleted to gateways. No subscription events yet.
• Internal gateway API: GET /api/internal/v1/apis, GET /api/internal/v1/apis/{apiId} (by gateway token); returns API YAML. No subscription payload today.

2.2 Gateway-Controller

• Storage: SQLite/Postgres with deployments (id, gateway_id, display_name, version, context, kind, handle, status, …) and api_keys (id, apiId, name, api_key, …). No applications or subscriptions tables.
• REST API: /apis, /apis/{id}, /apis/{id}/api-keys (create, list, regenerate, update, delete). No /apis/{id}/subscriptions yet.
• Control plane client: Consumes WebSocket events (api.deployed, api.undeployed, api.deleted, apiKey.created, apiKey.updated, apiKey.revoked). No subscription event handlers.
• API key sync: Platform pushes API key create/update/revoke via WebSocket; gateway persists in api_keys and uses for validation. Same pattern can be used for subscriptions.

2.3 Policy Engine

• Auth: JWT (or other) policy validates token and can put claims into request metadata. Analytics already uses x-wso2-application-id (and name/owner) from metadata (AppIDKey in internal/analytics/constants.go). So “Application” at runtime = identifier set by auth policy (e.g. from JWT azp or client_id).
• Route metadata: Envoy sends xds.route_metadata with api_id, api_name, api_version, context, etc. So policy has both “application id” (from auth) and “api id” (from route) for subscription check.
• No subscription check today: No policy verifies “this application is subscribed to this API.”

---

3. Data Model

3.1 Application Identifier

• Source of truth for “Application”: Tokens are issued per application (e.g. OAuth2 client / DevPortal application). The auth policy (e.g. JWT) will place the application identifier in request metadata (e.g. x-wso2-application-id), typically from JWT claim azp or client_id.
• Recommendation: Use a single string application ID (UUID or opaque ID). Platform and gateway both store subscriptions keyed by application_id and api_id. No need to replicate full “Application” entity in the gateway if we only need to validate (application_id, api_id) pairs.

3.2 Platform-API: New Tables

applications

• uuid (PK) — application identifier (align with token claim if possible).
• organization_uuid (FK → organizations).
• name — display name.
• description (optional).
• created_at, updated_at.
• Optional: external_ref_id if apps are created in an external IdP/DevPortal.

subscriptions

• uuid (PK).
• api_uuid (FK → rest_apis).
• application_uuid (FK → applications).
• organization_uuid (FK → organizations).
• status — e.g. ACTIVE, INACTIVE, REVOKED.
• created_at, updated_at.
• UNIQUE(api_uuid, application_uuid) (one subscription per API–application pair).

Indexes: (api_uuid), (application_uuid), (organization_uuid), (status).

3.3 Gateway-Controller: New Tables

applications (minimal, for FK and optional display)

• id (PK) — same as platform application uuid.
• gateway_id — gateway instance.
• name (optional).
• created_at, updated_at.
• UNIQUE(id, gateway_id).

subscriptions

• id (PK) — subscription uuid (or composite key).
• api_id (FK → deployments.id) — gateway’s API config id.
• application_id (FK → applications.id).
• gateway_id.
• status — ACTIVE / INACTIVE / REVOKED.
• created_at, updated_at.
• UNIQUE(api_id, application_id, gateway_id).

Indexes: (api_id), (application_id), (gateway_id), (status) for fast “is this app subscribed to this API?” lookups.

---

4. API Design

4.1 Platform-API: REST — /rest-apis/{apiId}/subscriptions

• POST /api/v1/rest-apis/{apiId}/subscriptions
  Body: { "applicationId": "uuid", "status": "ACTIVE" }.
  Create subscription; return 201 + subscription representation. Validate apiId and applicationId belong to same org.

• GET /api/v1/rest-apis/{apiId}/subscriptions
  Query: optional applicationId, status.
  Return list of subscriptions for the API (org-scoped).

• GET /api/v1/rest-apis/{apiId}/subscriptions/{subscriptionId}
  Return single subscription (org-scoped).

• PUT /api/v1/rest-apis/{apiId}/subscriptions/{subscriptionId}
  Body: { "status": "ACTIVE"|"INACTIVE"|"REVOKED" } (and optionally other fields).
  Update subscription.

• DELETE /api/v1/rest-apis/{apiId}/subscriptions/{subscriptionId}
  Remove subscription (or soft-delete via status).

Applications (if not managed elsewhere):

• If platform must create applications: POST/GET/GET by id/PUT/DELETE /api/v1/applications (org-scoped).
• If applications are created only in DevPortal/STS, platform might only need a minimal “application registry” or just store application_id in subscriptions as a string and validate existence via DevPortal/STS when needed. Plan assumes we add at least applications table and optional CRUD for it.

4.2 Gateway-Controller: REST — /apis/{apiId}/subscriptions

• POST /apis/{apiId}/subscriptions
  Body: { "applicationId": "uuid", "status": "ACTIVE", "subscriptionId": "uuid" }.
  Create subscription for this gateway (apiId = deployment id). Used by control plane sync and/or admin.

• GET /apis/{apiId}/subscriptions
  List subscriptions for the API (optional filters: applicationId, status).

• GET /apis/{apiId}/subscriptions/{subscriptionId}
  Get one subscription.

• PUT /apis/{apiId}/subscriptions/{subscriptionId}
  Update (e.g. status).

• DELETE /apis/{apiId}/subscriptions/{subscriptionId}
  Remove subscription.

All scoped by gateway (implicit gateway_id from auth or config).

---

5. WebSocket & Sync (Gateway-Controller)

5.1 New Event Types (Platform → Gateway)

• subscription.created
  Payload: apiId (platform API uuid), subscriptionId, applicationId, status, optional applicationName.
  Gateway maps platform apiId to local deployment id(s) for that API and inserts/updates subscription(s) in its DB.

• subscription.updated
  Payload: apiId, subscriptionId, applicationId, status.
  Gateway updates existing subscription.

• subscription.deleted
  Payload: apiId, subscriptionId, applicationId.
  Gateway deletes or marks subscription inactive.

When a single API is deployed to multiple gateways, platform can broadcast to each gateway; each gateway only applies subscriptions for APIs it knows (by deployment id).

5.2 Gateway-Controller Handling

• In WebSocket message dispatcher (e.g. gateway/gateway-controller/pkg/controlplane/client.go), add cases for subscription.created, subscription.updated, subscription.deleted.
• Resolve platform apiId to gateway’s deployment id (same as current deployment event flow). If API not deployed on this gateway, ignore or store for when API is later deployed (implementation choice).
• Persist to gateway’s subscriptions (and optionally applications) table; no need to call back platform for full list on each event if events are authoritative.

5.3 Initial / Bulk Sync (Optional but Recommended)

• On WebSocket connect or on demand: platform could send subscriptions.snapshot or gateway could call GET /api/internal/v1/apis/{apiId}/subscriptions (new internal endpoint) to fetch all subscriptions for APIs deployed to that gateway.
• Ensures gateway has full state after reconnect or first connect. Prefer one bulk endpoint per API or one per gateway (list subscriptions for all APIs of the org/gateway).

---

6. Policy Engine: Subscription Validation

6.1 Behaviour

• After auth (e.g. JWT) runs, request metadata should contain application id (e.g. x-wso2-application-id).
• Route metadata contains api id (e.g. from Envoy api_id).
• Subscription validation policy:
  • If subscription validation is disabled for the API/route: skip check, continue.
  • If enabled:
    • Read application id from request metadata. If missing → 403 Forbidden (or 401).
    • Read api id from route metadata.
    • Look up (api_id, application_id) in subscription store (in-memory cache backed by gateway-controller data).
    • If subscribed (e.g. status ACTIVE) → continue.
    • Else → 403 Forbidden.

6.2 Where Subscription Data Lives in Policy Engine

• Policy engine gets config via xDS from gateway-controller. So gateway-controller should include “subscription validation” data in xDS (e.g. list of (api_id, application_id) for ACTIVE subscriptions, or a flag per API “subscription required” plus that list).
• Alternatively, policy engine could query gateway-controller admin API at runtime (higher latency). Prefer xDS so subscription data is cached in the policy engine and no extra network call per request.

6.3 Implementation Options

• Option A — New policy “subscriptionValidation”:
  • New policy in policy-engine (and Policy Hub, if/when you add it). Config: e.g. enabled, applicationIdHeader (default x-wso2-application-id), forbiddenMessage.
  • Policy runs after JWT (or auth). Reads app id from metadata, api id from route, checks in-memory map received via xDS.
  • Requires gateway-controller to push subscription data over xDS (new resource or extend existing policy config).
• Option B — Extend JWT (or auth) policy:
  • Add optional “subscriptionValidation: true” and same semantics inside the existing policy. Tighter coupling; less flexible.
• Recommendation: Option A — dedicated subscriptionValidation policy. Clear separation; can be toggled per API/route; reuses existing xDS and metadata conventions.

6.4 xDS Contract (Gateway-Controller → Policy Engine)

• Add a “subscriptions” or “subscription_validation” resource in xDS (or embed in existing policy config): for each API (by api_id) that has subscription validation enabled, send set of allowed application_ids (or list of (api_id, application_id) with status).
• Policy engine on load: build in-memory set/map; on request, check (api_id, application_id) in set.
• When gateway-controller receives subscription events, update DB and push updated xDS snapshot so policy engine gets new set without restart.

---

7. Implementation Order (Phased)

Phase 1 — Data & Platform-API

1. Add applications and subscriptions tables to platform-api (schema.sql, schema.sqlite.sql, schema.postgres.sql) and run migrations.
2. Add repository layer: ApplicationRepository, SubscriptionRepository (CRUD).
3. Add Applications CRUD (if needed): handler + routes, e.g. /api/v1/applications.
4. Add /api/v1/rest-apis/{apiId}/subscriptions CRUD in platform-api (handler, service, repository). Update OpenAPI spec and regenerate client/server code.
5. (Optional) Internal endpoint for gateways: e.g. GET /api/internal/v1/subscriptions (by gateway/org) or GET /api/internal/v1/apis/{apiId}/subscriptions for bulk sync.

Phase 2 — Gateway-Controller Storage & REST

1. Add applications and subscriptions tables in gateway-controller (SQLite + Postgres migrations in existing migration flow).
2. Extend storage interface and sql_store: SaveSubscription, GetSubscription, ListSubscriptionsByAPI, UpdateSubscription, DeleteSubscription; same for applications if needed.
3. Add OpenAPI paths and schemas for /apis/{apiId}/subscriptions (POST, GET, GET by id, PUT, DELETE). Generate code (oapi-codegen).
4. Implement handlers that use storage and gateway_id from context/config.

Phase 3 — WebSocket & Sync

1. Platform: define event payloads subscription.created, subscription.updated, subscription.deleted (e.g. in platform-api/src/internal/model/gateway_event.go or similar).
2. Platform: on subscription create/update/delete, determine target gateways (e.g. gateways that have this API deployed), and broadcast event to those gateways’ WebSocket connections (reuse existing gateway events service).
3. Gateway-controller: in WebSocket client, handle new event types; map platform apiId to deployment id; persist to subscriptions (and applications) table.
4. (Optional) Platform: implement internal GET subscriptions for gateway; gateway-controller: on connect or periodically, fetch full subscription list for its APIs and reconcile local DB.

Phase 4 — Policy Engine & xDS

1. Gateway-controller: add xDS resource or extend policy config to include “subscription validation” data: for each api_id with subscription validation enabled, set of allowed application_ids (from subscriptions table with status=ACTIVE).
2. Policy engine: add subscriptionValidation policy (policy.yaml + Go). Parameters: e.g. enabled, applicationIdMetadataKey (default x-wso2-application-id), forbiddenStatusCode, forbiddenMessage. Execution: read application_id from metadata, api_id from route metadata; check in map from xDS; return 403 if not subscribed.
3. Wire policy into builder/templates so it can be compiled and configured per API (when you add Policy Hub support, the “enable subscription validation” toggle will attach this policy).
4. Ensure JWT (or auth) policy sets x-wso2-application-id from token claim (e.g. azp or client_id). Document required claim for application id.

Phase 5 — Testing & Docs

1. Unit tests: repositories, handlers, sync logic, policy.
2. Integration tests: create API → create application → create subscription → deploy API → trigger event → verify gateway has subscription → call API with token (with/without subscription) and assert 200 vs 403.
3. Update README/specs: data model, APIs, WebSocket events, and how to enable subscription validation per API.

---

8. File / Component Checklist (Summary)

Area	Action
platform-api
internal/database/schema*.sql	Add applications, subscriptions; indexes.
internal/model/	application.go, subscription.go.
internal/repository/	application_repository.go, subscription_repository.go.
internal/service/	application_service.go, subscription_service.go (and wire into api/gateway events).
internal/handler/	subscription_handlers.go for rest-apis; optional application_handlers.go.
resources/openapi.yaml	Paths for /rest-apis/{apiId}/subscriptions, optional /applications.
internal/service/gateway_events.go	Emit subscription.created/updated/deleted; add internal GET subscriptions if needed.
internal/websocket/	No change if events are JSON payloads; ensure payload size limits allow new events.
gateway-controller
pkg/storage/sqlite.go (and postgres)	Migrations: applications, subscriptions tables.
pkg/storage/interface.go, sql_store.go	Subscription (and application) CRUD.
pkg/models/	Subscription, Application structs.
resources/openapi.yaml	/apis/{id}/subscriptions CRUD.
pkg/api/handlers/	Subscription handlers.
pkg/controlplane/events.go	Subscription event payload structs.
pkg/controlplane/client.go	Handle subscription.created/updated/deleted; resolve apiId → deployment id; persist.
xDS	New resource or extended config for subscription allow-list per API.
policy-engine
New policy	e.g. policies/subscription-validation/ (policy.yaml + Go); read metadata + route; check allow-list; 403 if not subscribed.
xDS client / handler	Parse subscription validation config from xDS and build in-memory map.
Docs	How to enable subscription validation; required JWT claim for application id.

---

9. Security & Consistency Notes

• Authorization: Platform subscription APIs must enforce org/project scope (only allow managing subscriptions for APIs and applications in the same organization).
• Gateway: Subscription REST API should be protected (e.g. same auth as existing admin API or gateway token). Internal GET subscriptions endpoint must require gateway token.
• Idempotency: Subscription create/update events should be idempotent (same subscriptionId → upsert) so duplicate or out-of-order WebSocket messages do not leave gateway inconsistent.
• API deletion: When an API is deleted (or undeployed), gateway should remove or invalidate its subscriptions for that API (cascade or on api.deleted event).

---

10. Open Points for Review

1. Application ownership: Are applications created only in DevPortal/STS, or should platform-api host full Application CRUD? (Affects whether we add /api/v1/applications or only reference applicationId in subscriptions.)
2. Mapping platform apiId → gateway deployment id: Platform uses API uuid; gateway uses deployment id (often same as api uuid when single deployment). Confirm convention (e.g. deployment id = platform api uuid for REST APIs).
3. Subscription validation default: Should “subscription required” be opt-in per API (via policy attachment) or default on for all APIs? Plan assumes opt-in via policy.
4. Bulk sync: Prefer adding GET /api/internal/v1/.../subscriptions for gateways vs. only relying on events (events simpler; bulk sync avoids gaps after reconnect).

[malinthaprasan]

A few suggestions:

1. Use /subscriptions as a root-level resource

What if we do use a root-level /subscriptions resource. This way, we won't need to implement separate subscription APIs for each API type. Subscriptions can simply be filtered by apiId, which could represent any type of API - REST, MCP, GraphQL, WebSocket, etc.

For example:

• POST /api/v1/subscriptions with apiId and applicationId in the body
• GET /api/v1/subscriptions?apiId={apiId}
• GET /api/v1/subscriptions?applicationId={appId}
• GET/PUT/DELETE /api/v1/subscriptions/{subscriptionId}

The same approach can be applied on the gateway-controller side as well.

2. +1 for a dedicated subscription validation policy (6.3 Option A).

A dedicated policy can pick up the authentication state from the auth context and handle subscription validation in one place - keeping it cleanly separated from auth logic.

3. Handle gateway reconnection scenarios

We need to account for cases where a gateway is offline when a subscription event is sent and reconnects later. There should be a mechanism to sync missed subscriptions upon reconnection - similar to the approach we're currently implementing for syncing API keys and API deployments.

4. Application deletion cascade

When an application is deleted cascade-delete any existing subscriptions of that app.

A couple of Questions.

1. How do we perform subscription validation for API Keys: We need to get the associated application for API key and we need a way for that.
2. How do we perform some rate limiting etc based on a subscription?