[Proposal] Federated subscription support for standalone devportal

[Piumal1999]

Problem

The standalone developer portal is designed to host APIs from any gateway — WSO2 Platform gateway, Kong, Apigee, AWS API Gateway, and others. However, the current implementation hardcodes the WSO2 API Platform subscription and API key flow inline across controllers and services. Extending the portal to support a second gateway requires modifying the same logic in multiple places, with no clear boundary between gateway-specific behaviour and generic portal logic.

Each gateway has its own conventions for how a developer obtains access to an API:

• Subscription model: some gateways maintain an explicit subscription resource (eg: with a token); others treat subscription as a local permission record with no gateway-side representation.
• Credential model: some gateways issue credentials at subscription time; others issue them independently.
• Plan enforcement: some gateways have named rate-limit plans that must be referenced at key creation or association time; others enforce throttling at the API policy level.

Without a clear abstraction, every new gateway adds conditional branches that erode maintainability.

Proposed Solution

Introduce a gateway adapter layer that encapsulates all gateway-specific credential operations behind a narrow, consistent interface. The portal owns the subscription record as a local permission entry; the adapter handles only the gateway-side operations. The existing Platform gateway related implementation becomes the first adapter. New gateways slot in by adding a single folder and a config block — no changes to core portal logic.

---

Scope

In scope:

• API-scoped subscription management (subscribe, unsubscribe, list)
• API-scoped API key lifecycle (generate, regenerate, revoke, list)
• A seam (keyIssuer.js) for future in-portal key generation, decoupled from the current control-plane delegation
• UI flow adaptation based on gateway capability (token-based-subscription vs. api-key-only)

Out of scope:

• Application-based subscriptions (wso2/cloud-gateway): We keep the current implementation as it is as the core concepts are different.

---

Data Model

The portal maintains a local mirror of subscription and key metadata. The gateway remains the source of truth for key values; the portal stores only what it needs to address gateway-side resources in future operations.

DP_API_SUBSCRIPTION (extended)

Column	Description
SUB_ID	Local primary key
ORG_ID	Portal organisation
API_ID	Portal API reference
POLICY_ID	Subscription plan name
CREATED_BY	Portal user who subscribed
GATEWAY_REF_ID	Gateway-side subscription identifier (null for key-only gateways)
SUB_TOKEN	Subscription token returned by the gateway, retrievable by the user
APP_ID	Nullable now — used only by the legacy application-based flow

DP_GATEWAY_ENVIRONMENT (new)

Stores the gateway-specific configuration per organization. Allows different organizations to point to different gateway instances.

Column	Description
ENV_ID	Local primary key
ORG_ID	Portal organisation
GATEWAY_TYPE	Gateway type identifier (e.g., wso2/api-platform, kong)
CONFIG	JSON blob holding gateway-specific settings (control plane URL, credentials, etc.)
CREATED_AT	Creation timestamp
UPDATED_AT	Last updated timestamp

The adapter's init(config) method receives the parsed JSON from the CONFIG column for the organisation's registered gateway instance.

DP_API_KEY (new)

Column	Description
KEY_ID	Local primary key
ORG_ID	organisation
API_ID	devportal API reference
CREATED_BY	user who generated the key
NAME	Key label
GATEWAY_REF_ID	Gateway-side key identifier, required for revoke and regenerate
EXPIRES_AT	Expiry timestamp (null if the key does not expire)
REVOKED_AT	Revocation timestamp (null if active)
CREATED_AT	Creation timestamp

The raw key value is never persisted. It is returned to the caller once for display and must not be logged or stored.

---

Adapter Interface

Each adapter is a Node.js module in src/gatewayAdapters/<name>/index.js that exports the following contract:

module.exports = {
  // Identity
  gatewayType: 'wso2/api-platform',   // must match DP_API_METADATA.GATEWAY_TYPE
  displayName: 'WSO2 API Platform',

  // Called once at startup with the adapter's config.yaml slice.
  init(config) { },

  // Required. Every adapter must be able to issue an API key.
  async generateApiKey(ctx) {
    // returns { apiKey, gatewayKeyId, expiresAt?, raw? }
    // gatewayKeyId is required — the dispatcher rejects a blank value.
  },

  // Optional pair. Implement both or neither.
  // Present only on gateways with a real gateway-side subscription resource.
  async subscribe(ctx)   { /* returns { gatewayRefId, token?, raw? } */ },
  async unsubscribe(ctx) { /* void; ctx.payload.gatewayRefId required  */ },

  // Optional individually.
  async regenerateApiKey(ctx) { /* returns { apiKey, gatewayKeyId, expiresAt?, raw? } */ },
  async revokeApiKey(ctx)     { /* void; ctx.payload.gatewayKeyId required             */ },
};

Capability detection. The adapter declares no explicit capability flags. The dispatcher introspects method presence at runtime: typeof adapter.subscribe === 'function' determines whether a gateway is token-based. This is also surfaced to the UI through the API metadata response (hasGatewaySubscription).

Contracts:

• revokeApiKey and unsubscribe must be idempotent — a "not found" response from the gateway is treated as success.
• gatewayKeyId is the durable handle for all subsequent key operations. If an adapter returns a blank gatewayKeyId from generateApiKey, the dispatcher rejects the result with a 500 error.
• The raw key value in apiKey must not be logged or included in raw.

Adapter file layout (by convention):

src/gatewayAdapters/<gatewayType>/
├── index.js            Adapter implementation (the interface above)
├── config.schema.js    Validates and normalizes config.yaml slice for this adapter
├── keyIssuer.js        Single point of contact for key operations
└── gatewayDelivery.js  Optional — pushes issued keys and details to the gateway when needed

keyIssuer.js is the designated swap point for when key generation moves from control-plane delegation to direct in-portal generation.

---

Architecture

Component Overview

flowchart TB
    UI[Developer Portal UI]

    subgraph Portal Backend
        R[Routes\n/gateway-subscriptions\n/gateway-api-keys]
        SS[subscriptionService\nDispatcher]
        AKS[apiKeyService\nDispatcher]
        DTO[APIDTO\nhasGatewaySubscription]
        L[Adapter Loader]
    end

    subgraph Adapters
        A1[wso2/api-platform]
        A2[kong ...]
        AN[future adapters]
        KI[keyIssuer.js]
        GD[gatewayDelivery.js]
    end

    subgraph Persistence
        DB1[(DP_API_SUBSCRIPTION)]
        DB2[(DP_API_KEY)]
        DB3[(DP_GATEWAY_ENVIRONMENT)]
    end

    subgraph External
        CP[(WSO2 API Platform\nControl Plane)]
        GW[(External Gateway)]
    end

    UI --> R
    UI --> DTO
    R --> SS
    R --> AKS
    SS --> L
    SS --> DB1
    SS --> DB3
    AKS --> L
    AKS --> DB2
    AKS --> DB3
    DTO --> L
    L -. init .-> DB3
    L --> A1
    L --> A2
    L --> AN
    A1 --> KI
    A1 --> GD
    KI --> CP
    GD --> GW

Loading

Adapter Boot Sequence

sequenceDiagram
    participant Boot as Startup
    participant Loader as Adapter Loader
    participant FS as gatewayAdapters/
    participant Adapter as Adapter Module
    participant DB as DP_GATEWAY_ENVIRONMENT

    Boot->>Loader: load(rootConfig, orgId)
    Loader->>FS: Scan subdirectories for index.js
    loop Each discovered adapter
        Loader->>Adapter: require(index.js)
        Loader->>Adapter: Validate shape (gatewayType, displayName, generateApiKey)
        Loader->>DB: Query CONFIG for orgId + gatewayType
        DB-->>Loader: Per-org gateway config
        Loader->>Adapter: init(orgConfig)
        Adapter-->>Loader: Ready
    end
    Loader-->>Boot: Registry populated (org-specific)

Loading

---

Subscription and Key Flows

Token-Based Gateway Flow

Applies when the adapter implements subscribe. The gateway has its own subscription resource that returns a subscription token. The API key is a separate credential used for runtime invocation and is independent of the subscription lifecycle.

sequenceDiagram
    participant Dev as Developer
    participant UI
    participant Disp as Dispatcher
    participant A as Adapter
    participant GW as Gateway / Control Plane
    participant DB as DP_API_SUBSCRIPTION / DP_API_KEY

    Dev->>UI: Subscribe to API (select plan)
    UI->>Disp: POST /gateway-subscriptions
    Disp->>A: subscribe(ctx)
    A->>GW: Create gateway-side subscription
    GW-->>A: { subscriptionId, subscriptionToken }
    A-->>Disp: { gatewayRefId, token }
    Disp->>DB: INSERT DP_API_SUBSCRIPTION\n(GATEWAY_REF_ID, SUB_TOKEN)
    Disp-->>UI: { subscriptionId, subscriptionToken }
    UI-->>Dev: Subscription created

    Note over Dev,DB: The subscription token is stored and retrievable.<br/>The API key lifecycle is independent.

    Dev->>UI: Generate API key
    UI->>Disp: POST /gateway-api-keys/generate
    Disp->>A: generateApiKey(ctx)
    A->>GW: Issue API key
    GW-->>A: { apiKey, gatewayKeyId }
    A-->>Disp: { apiKey, gatewayKeyId }
    Disp->>DB: INSERT DP_API_KEY (GATEWAY_REF_ID)
    Disp-->>UI: { apiKey, keyId }
    UI-->>Dev: Display key (not stored — copy now)

Loading

Key-Only Gateway Flow

Applies when the adapter does not implement subscribe. The gateway has no subscription resource. The portal creates a local permission record and immediately issues a key in a single user action.

sequenceDiagram
    participant Dev as Developer
    participant UI
    participant Disp as Dispatcher
    participant A as Adapter
    participant GW as Gateway
    participant DB as DP_API_SUBSCRIPTION / DP_API_KEY

    Dev->>UI: Subscribe and get API key (single action)
    UI->>Disp: POST /gateway-subscriptions + POST /gateway-api-keys/generate
    Disp->>DB: INSERT DP_API_SUBSCRIPTION\n(no GATEWAY_REF_ID)
    Disp->>A: generateApiKey(ctx)
    A->>GW: Issue API key
    GW-->>A: { apiKey, gatewayKeyId }
    A-->>Disp: { apiKey, gatewayKeyId }
    Disp->>DB: INSERT DP_API_KEY (GATEWAY_REF_ID)
    Disp-->>UI: { subscription, apiKey, keyId }
    UI-->>Dev: Display key (not stored — copy now)

Loading

Failure Handling

Write operations follow a gateway-first, then persist pattern. If the local database write fails after a successful gateway operation, the dispatcher surfaces a 500 error. The gateway-side resource may be left in an inconsistent state; administrators can reconcile manually using the stored GATEWAY_REF_ID.

For subscriptions, the dispatcher attempts a best-effort adapter.unsubscribe call before surfacing the error, to minimise orphan gateway-side subscriptions. Rollback errors are logged and suppressed so the original failure is preserved.

---

UI Gateway Capability Discovery

The UI determines whether to render a token-based or key-only flow by reading the hasGatewaySubscription field included in the API metadata response. This field is computed server-side by looking up the registered adapter for the API's GATEWAY_TYPE and checking for the presence of a subscribe method. No additional API call is required.

APIDTO.apiInfo.hasGatewaySubscription
  → true   → render subscribe step, then separate generate key step
  → false  → render combined subscribe-and-generate step

---

Adding a New Gateway Adapter

Built-in Adapters

For adapters distributed with the portal:

1. Create src/gatewayAdapters/<name>/index.js exporting at minimum gatewayType, displayName, and generateApiKey. Add subscribe and unsubscribe only if the gateway has its own subscription resource.
2. Add a gateways.<name>: block to config.yaml with the configuration expected by the adapter's init function.
3. For each organisation that uses this gateway, insert a row into DP_GATEWAY_ENVIRONMENT with GATEWAY_TYPE = '<name>' and CONFIG containing the organisation-specific gateway settings (control plane URL, API credentials, etc.).
4. Onboard APIs with gatewayType: '<name>' via the existing API metadata REST endpoint.
5. Restart. The adapter loader discovers and initialises the adapter automatically, reading per-org config from DP_GATEWAY_ENVIRONMENT.

Custom Adapters (Docker)

For custom adapters maintained outside the portal codebase:

1. Create an adapter module following the same interface (gatewayType, displayName, init, generateApiKey, etc.).
2. Mount the adapter folder at /app/src/gatewayAdapters/<name>/ inside the container.
3. Add a gateways.<name>: block to the mounted config.yaml.
4. Insert a row into DP_GATEWAY_ENVIRONMENT for each organisation.
5. Restart the container. The adapter loader discovers and initialises the mounted adapter.

Example Docker Compose mount:

services:
  portal:
    image: devportal:latest
    volumes:
      - ./custom-adapters/gateway-abc:/app/gatewayAdapters/gateway-abc
      - ./config.yaml:/app/config.yaml

Custom Adapters (Executable)

For deployments using the compiled/packaged executable:

1. Create the adapter module in the same structure.
2. Extract or mount the adapter folder next to the executable (e.g., ./adapters/<name>/).
3. Ensure the executable's config.yaml has a gateways.<name>: block.
4. Insert a row into DP_GATEWAY_ENVIRONMENT for each organisation.
5. Restart the executable. The adapter loader discovers the adapter in the mounted folder.

No changes to core portal logic are required in any deployment model.

---

Why Applications Are Not Federated

The portal has two distinct credential models:

Model	Used by	Credential type
Application-based	cloud-gateway	OAuth2 client credentials, scoped to an application
API-key-based	WSO2 API Platform, Kong, AWS, etc.	API key, scoped directly to an API

These models are not variations of the same thing. They differ in lifecycle ownership, credential shape, and the portal concerns they involve. Trying to unify them under a single adapter interface requires the interface to accommodate concepts that are only meaningful to one side — producing an abstraction that fits neither well.

---

What This Is Not

• Not a full credential vault. The portal stores metadata (reference IDs, expiry) only. Key values are returned to the user for display and are not stored.
• Not a rewrite of existing flows. Choreo Connect / wso2/cloud-gateway keeps its existing controllers unchanged. Only the WSO2 API Platform flow moves behind an adapter in this iteration.
• Not a multi-environment fan-out layer. Each API has a single GATEWAY_TYPE. Multi-environment replication (one key pushed to several gateway instances) is out of scope.
• Not a configuration UI. The DP_GATEWAY_ENVIRONMENT table is seeded via direct SQL or the portal's internal API. Administrative UI for managing gateway configurations is future work.