Add /api-portals CRUD resource to platform-api

platform-api/internal/apperror/catalog.go

@@ -148,6 +148,12 @@ var (
 	ApplicationExists    = def(CodeApplicationExists, http.StatusConflict, "An application with this name already exists.")
 )
 
+// API Portal entries.
+var (
+	APIPortalNotFound = def(CodeAPIPortalNotFound, http.StatusNotFound, "The specified API Portal could not be found.")
+	APIPortalExists   = def(CodeAPIPortalExists, http.StatusConflict, "An API Portal with this handle already exists in the organization.")
+)
+
 // Subscription entries.
 var (
 	SubscriptionNotFound     = def(CodeSubscriptionNotFound, http.StatusNotFound, "The specified subscription could not be found.")

platform-api/internal/apperror/codes.go

@@ -130,6 +130,12 @@ const (
 	CodeApplicationExists   = "APPLICATION_EXISTS"
 )
 
+// API Portal domain codes.
+const (
+	CodeAPIPortalNotFound = "API_PORTAL_NOT_FOUND"
+	CodeAPIPortalExists   = "API_PORTAL_EXISTS"
+)
+
 // Subscription domain codes.
 const (
 	CodeSubscriptionNotFound     = "SUBSCRIPTION_NOT_FOUND"

platform-api/internal/constants/constants.go

@@ -207,6 +207,23 @@ var ValidGatewayTokenStatuses = map[string]bool{
 	GatewayTokenStatusRevoked: true,
 }
 
+// API Portal status constants.
+const (
+	APIPortalStatusPending = "pending"
+	APIPortalStatusActive  = "active"
+	APIPortalStatusFailed  = "failed"
+)
+
+// API Portal outbound-auth constants. The scheme is a custom RFC 7235 name,
+// not OAuth 2.0 Bearer; the portal middleware sha256s the raw for verification.
+const (
+	// APIPortalSharedKeyAuthScheme is the Authorization-header scheme name; matched case-insensitively by the portal.
+	APIPortalSharedKeyAuthScheme = "SharedKey"
+
+	// APIPortalSharedKeyHexLength is the required raw-key length in hex chars (32 bytes of entropy).
+	APIPortalSharedKeyHexLength = 64
+)
+
 // ValidArtifactKinds holds accepted values for artifacts.type for the core (non-plugin)
 // artifact kinds. Plugin-owned kinds (e.g. WebSubApi, WebBrokerApi) are registered
 // into the ArtifactTableRegistry during plugin Init.

platform-api/internal/database/schema.postgres.sql

@@ -399,6 +399,25 @@ CREATE TABLE IF NOT EXISTS mcp_proxies (
     UNIQUE(organization_uuid, handle)
 );
 
+-- API Portals table (registration of an API Portal instance for an organization)
+CREATE TABLE IF NOT EXISTS api_portals (
+    uuid              VARCHAR(40)  PRIMARY KEY,
+    organization_uuid VARCHAR(40)  NOT NULL,
+    handle            VARCHAR(40)  NOT NULL,
+    display_name      VARCHAR(255) NOT NULL,
+    description       VARCHAR(1023),
+    url               VARCHAR(500),
+    status               VARCHAR(20)  NOT NULL DEFAULT 'pending',
+    internal_auth_key BYTEA        NOT NULL,
+    metadata             BYTEA,
+    created_by           VARCHAR(200),
+    created_at           TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
+    updated_by           VARCHAR(200),
+    updated_at           TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
+    UNIQUE (organization_uuid, handle)
+);
+
 
 CREATE TABLE IF NOT EXISTS api_keys (
     uuid VARCHAR(40) PRIMARY KEY,
@@ -473,6 +492,7 @@ CREATE INDEX IF NOT EXISTS idx_llm_proxies_provider_uuid ON llm_proxies(provider
 CREATE INDEX IF NOT EXISTS idx_llm_proxies_org ON llm_proxies(organization_uuid);
 CREATE INDEX IF NOT EXISTS idx_mcp_proxies_project ON mcp_proxies(project_uuid);
 CREATE INDEX IF NOT EXISTS idx_mcp_proxies_org ON mcp_proxies(organization_uuid);
+CREATE INDEX IF NOT EXISTS idx_api_portals_org ON api_portals(organization_uuid);
 CREATE INDEX IF NOT EXISTS idx_api_keys_artifact ON api_keys(artifact_uuid);
 CREATE INDEX IF NOT EXISTS idx_applications_org ON applications(organization_uuid);
 CREATE INDEX IF NOT EXISTS idx_applications_project_id ON applications(organization_uuid, project_uuid);

platform-api/internal/database/schema.sqlite.sql

@@ -399,6 +399,25 @@ CREATE TABLE IF NOT EXISTS mcp_proxies (
     UNIQUE(organization_uuid, handle)
 );
 
+-- API Portals table (registration of an API Portal instance for an organization)
+CREATE TABLE IF NOT EXISTS api_portals (
+    uuid              VARCHAR(40)  PRIMARY KEY,
+    organization_uuid VARCHAR(40)  NOT NULL,
+    handle            VARCHAR(40)  NOT NULL,
+    display_name      VARCHAR(255) NOT NULL,
+    description       VARCHAR(1023),
+    url               VARCHAR(500),
+    status               VARCHAR(20)  NOT NULL DEFAULT 'pending',
+    internal_auth_key BLOB         NOT NULL,
+    metadata             BLOB,
+    created_by           VARCHAR(200),
+    created_at           DATETIME     DEFAULT CURRENT_TIMESTAMP,
+    updated_by           VARCHAR(200),
+    updated_at           DATETIME     DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
+    UNIQUE (organization_uuid, handle)
+);
+
 -- API Keys table (stores API keys for artifacts with hashes as JSON string)
 CREATE TABLE IF NOT EXISTS api_keys (
     uuid VARCHAR(40) PRIMARY KEY,
@@ -472,6 +491,7 @@ CREATE INDEX IF NOT EXISTS idx_llm_proxies_provider_uuid ON llm_proxies(provider
 CREATE INDEX IF NOT EXISTS idx_llm_proxies_org ON llm_proxies(organization_uuid);
 CREATE INDEX IF NOT EXISTS idx_mcp_proxies_project ON mcp_proxies(project_uuid);
 CREATE INDEX IF NOT EXISTS idx_mcp_proxies_org ON mcp_proxies(organization_uuid);
+CREATE INDEX IF NOT EXISTS idx_api_portals_org ON api_portals(organization_uuid);
 CREATE INDEX IF NOT EXISTS idx_api_keys_artifact ON api_keys(artifact_uuid);
 CREATE INDEX IF NOT EXISTS idx_rest_apis_org ON rest_apis(organization_uuid);
 CREATE INDEX IF NOT EXISTS idx_applications_org ON applications(organization_uuid);

platform-api/internal/database/schema.sqlserver.sql

@@ -450,6 +450,26 @@ CREATE TABLE dbo.mcp_proxies (
     UNIQUE(organization_uuid, handle)
 );
 
+-- API Portals table (registration of an API Portal instance for an organization)
+IF OBJECT_ID(N'dbo.api_portals', N'U') IS NULL
+CREATE TABLE dbo.api_portals (
+    uuid              VARCHAR(40)   PRIMARY KEY,
+    organization_uuid VARCHAR(40)   NOT NULL,
+    handle            VARCHAR(40)   NOT NULL,
+    display_name      VARCHAR(255)  NOT NULL,
+    description       VARCHAR(1023),
+    url               VARCHAR(500),
+    status               VARCHAR(20)    NOT NULL DEFAULT 'pending',
+    internal_auth_key VARBINARY(MAX) NOT NULL,
+    metadata             VARBINARY(MAX),
+    created_by           VARCHAR(200),
+    created_at           DATETIME2(7)   DEFAULT SYSUTCDATETIME(),
+    updated_by           VARCHAR(200),
+    updated_at           DATETIME2(7)   DEFAULT SYSUTCDATETIME(),
+    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
+    UNIQUE (organization_uuid, handle)
+);
+
 IF OBJECT_ID(N'dbo.api_keys', N'U') IS NULL
 CREATE TABLE dbo.api_keys (
     uuid VARCHAR(40) PRIMARY KEY,
@@ -554,6 +574,8 @@ IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = N'idx_mcp_proxies_project'
 CREATE INDEX idx_mcp_proxies_project ON dbo.mcp_proxies(project_uuid);
 IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = N'idx_mcp_proxies_org' AND object_id = OBJECT_ID(N'dbo.mcp_proxies'))
 CREATE INDEX idx_mcp_proxies_org ON dbo.mcp_proxies(organization_uuid);
+IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = N'idx_api_portals_org' AND object_id = OBJECT_ID(N'dbo.api_portals'))
+CREATE INDEX idx_api_portals_org ON dbo.api_portals(organization_uuid);
 IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = N'idx_api_keys_artifact' AND object_id = OBJECT_ID(N'dbo.api_keys'))
 CREATE INDEX idx_api_keys_artifact ON dbo.api_keys(artifact_uuid);
 IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = N'idx_api_keys_status' AND object_id = OBJECT_ID(N'dbo.api_keys'))

platform-api/internal/handler/api_portal.go

@@ -0,0 +1,183 @@
+/*
+ *  Copyright (c) 2026, WSO2 LLC. (http://www.wso2.org) All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ */
+
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"strings"
+
+	"github.com/wso2/api-platform/platform-api/api"
+	"github.com/wso2/api-platform/platform-api/internal/apperror"
+	"github.com/wso2/api-platform/platform-api/internal/constants"
+	"github.com/wso2/api-platform/platform-api/internal/middleware"
+	"github.com/wso2/api-platform/platform-api/internal/router"
+	"github.com/wso2/api-platform/platform-api/internal/service"
+
+	"github.com/wso2/api-platform/httpkit/httputil"
+)
+
+// APIPortalHandler exposes /api-portals CRUD.
+type APIPortalHandler struct {
+	svc      *service.APIPortalService
+	identity *service.IdentityService
+	slogger  *slog.Logger
+}
+
+// NewAPIPortalHandler constructs an APIPortalHandler.
+func NewAPIPortalHandler(svc *service.APIPortalService, identity *service.IdentityService, slogger *slog.Logger) *APIPortalHandler {
+	return &APIPortalHandler{svc: svc, identity: identity, slogger: slogger}
+}
+
+// CreateAPIPortal handles POST /api-portals.
+func (h *APIPortalHandler) CreateAPIPortal(w http.ResponseWriter, r *http.Request) error {
+	orgID, ok := middleware.GetOrganizationFromRequest(r)
+	if !ok {
+		return apperror.Unauthorized.New().WithLogMessage("organization claim not found in token")
+	}
+
+	var req api.CreateApiPortalRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		return apperror.NewValidation(err)
+	}
+
+	createdBy, err := resolveActorErr(r, h.identity, "create api portal")
+	if err != nil {
+		return err
+	}
+
+	resp, err := h.svc.CreateAPIPortal(&req, orgID, createdBy)
+	if err != nil {
+		return serviceError(err, fmt.Sprintf("failed to create api portal %q for org %s by user %s", req.Handle, orgID, createdBy))
+	}
+
+	setLocation(w, "api-portals", derefStr(resp.Handle))
+	httputil.WriteJSON(w, http.StatusCreated, resp)
+	return nil
+}
+
+// GetAPIPortal handles GET /api-portals/{apiPortalId}.
+func (h *APIPortalHandler) GetAPIPortal(w http.ResponseWriter, r *http.Request) error {
+	orgID, ok := middleware.GetOrganizationFromRequest(r)
+	if !ok {
+		return apperror.Unauthorized.New().WithLogMessage("organization claim not found in token")
+	}
+
+	handle := strings.TrimSpace(r.PathValue("apiPortalId"))
+	if handle == "" {
+		return apperror.ValidationFailed.New("API Portal ID is required")
+	}
+
+	resp, err := h.svc.GetAPIPortal(handle, orgID)
+	if err != nil {
+		return serviceError(err, fmt.Sprintf("failed to get api portal %q in org %s", handle, orgID))
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+// ListAPIPortals handles GET /api-portals.
+func (h *APIPortalHandler) ListAPIPortals(w http.ResponseWriter, r *http.Request) error {
+	orgID, ok := middleware.GetOrganizationFromRequest(r)
+	if !ok {
+		return apperror.Unauthorized.New().WithLogMessage("organization claim not found in token")
+	}
+
+	opts := parseListOptions(r)
+
+	resp, err := h.svc.ListAPIPortals(orgID, opts.Limit, opts.Offset, opts.SortBy, opts.SortOrder, opts.Search)
+	if err != nil {
+		return serviceError(err, fmt.Sprintf("failed to list api portals for org %s", orgID))
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+// UpdateAPIPortal handles PUT /api-portals/{apiPortalId}.
+func (h *APIPortalHandler) UpdateAPIPortal(w http.ResponseWriter, r *http.Request) error {
+	orgID, ok := middleware.GetOrganizationFromRequest(r)
+	if !ok {
+		return apperror.Unauthorized.New().WithLogMessage("organization claim not found in token")
+	}
+
+	handle := strings.TrimSpace(r.PathValue("apiPortalId"))
+	if handle == "" {
+		return apperror.ValidationFailed.New("API Portal ID is required")
+	}
+
+	var req api.UpdateApiPortalRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		return apperror.NewValidation(err)
+	}
+
+	updatedBy, err := resolveActorErr(r, h.identity, "update api portal")
+	if err != nil {
+		return err
+	}
+
+	resp, err := h.svc.UpdateAPIPortal(handle, &req, orgID, updatedBy)
+	if err != nil {
+		return serviceError(err, fmt.Sprintf("failed to update api portal %q in org %s by user %s", handle, orgID, updatedBy))
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+// DeleteAPIPortal handles DELETE /api-portals/{apiPortalId}.
+func (h *APIPortalHandler) DeleteAPIPortal(w http.ResponseWriter, r *http.Request) error {
+	orgID, ok := middleware.GetOrganizationFromRequest(r)
+	if !ok {
+		return apperror.Unauthorized.New().WithLogMessage("organization claim not found in token")
+	}
+
+	handle := strings.TrimSpace(r.PathValue("apiPortalId"))
+	if handle == "" {
+		return apperror.ValidationFailed.New("API Portal ID is required")
+	}
+
+	actor, err := resolveActorErr(r, h.identity, "delete api portal")
+	if err != nil {
+		return err
+	}
+
+	if err := h.svc.DeleteAPIPortal(handle, orgID, actor); err != nil {
+		return serviceError(err, fmt.Sprintf("failed to delete api portal %q in org %s by user %s", handle, orgID, actor))
+	}
+	w.WriteHeader(http.StatusNoContent)
+	return nil
+}
+
+// RegisterRoutes wires all /api-portals routes onto the shared mux.
+func (h *APIPortalHandler) RegisterRoutes(mux router.Router) {
+	base := constants.APIBasePath + "/api-portals"
+	mux.HandleFunc("POST "+base, middleware.MapErrors(h.slogger, h.CreateAPIPortal))
+	mux.HandleFunc("GET "+base, middleware.MapErrors(h.slogger, h.ListAPIPortals))
+	mux.HandleFunc("GET "+base+"/{apiPortalId}", middleware.MapErrors(h.slogger, h.GetAPIPortal))
+	mux.HandleFunc("PUT "+base+"/{apiPortalId}", middleware.MapErrors(h.slogger, h.UpdateAPIPortal))
+	mux.HandleFunc("DELETE "+base+"/{apiPortalId}", middleware.MapErrors(h.slogger, h.DeleteAPIPortal))
+}
+
+// derefStr returns the pointed-to string or "" when nil.
+func derefStr(p *string) string {
+	if p == nil {
+		return ""
+	}
+	return *p
+}