diff --git a/.github/workflows/devportal-integration-test.yml b/.github/workflows/devportal-integration-test.yml
index 83167bbae1..d9692ef3d8 100644
--- a/.github/workflows/devportal-integration-test.yml
+++ b/.github/workflows/devportal-integration-test.yml
@@ -18,12 +18,18 @@ permissions:
 
 jobs:
   rest-api-test:
-    name: REST API tests (${{ matrix.db }})
+    name: REST API tests (${{ matrix.db }}, ${{ matrix.mode }} mode)
     runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
       matrix:
         db: [sqlite, postgres]
+        # auth.authorization.mode — the whole suite runs in each. "role" is the
+        # shipped default; "scope" is what an issuer minting dp:* scopes directly
+        # uses. A matrix dimension rather than the both-modes `make test-rest-api`
+        # target so the four combinations run in parallel and CI wall-clock stays
+        # where it was. See portals/api-portal/it/README.md "Authorization modes".
+        mode: [scope, role]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -39,21 +45,21 @@ jobs:
       - name: Build API Portal image
         run: make -C portals/api-portal build
 
-      - name: Run REST API integration tests (${{ matrix.db }})
+      - name: Run REST API integration tests (${{ matrix.db }}, ${{ matrix.mode }} mode)
         env:
           PLATFORM_API_IMAGE: platform-api:it-api-portal
         run: |
           if [ "${{ matrix.db }}" = "postgres" ]; then
-            make -C portals/api-portal/it test-rest-api-postgres
+            make -C portals/api-portal/it test-rest-api-postgres-${{ matrix.mode }}
           else
-            make -C portals/api-portal/it test-rest-api
+            make -C portals/api-portal/it test-rest-api-${{ matrix.mode }}
           fi
 
       - name: Upload test reports
         uses: actions/upload-artifact@v4
         if: always()
         with:
-          name: rest-api-test-reports-${{ matrix.db }}
+          name: rest-api-test-reports-${{ matrix.db }}-${{ matrix.mode }}
           path: portals/api-portal/it/reports/
           retention-days: 7
 
diff --git a/portals/api-portal/configs/config-template.toml b/portals/api-portal/configs/config-template.toml
index c74ed22287..64465cedd7 100644
--- a/portals/api-portal/configs/config-template.toml
+++ b/portals/api-portal/configs/config-template.toml
@@ -92,12 +92,6 @@ pool_request_timeout_ms = 30000         # MSSQL only - per-query execution timeo
 encryption_key = ""     # 64-char hex — AES-256-GCM key for encrypting secrets at rest
 session_secret = ""     # 64-char hex — express-session signing secret
 
-# Static shared-secret header for calling the API Portal's own REST API.
-[api_portal.security.service_api_key]
-enabled = true
-header_name = "x-wso2-api-key"
-value = ""
-
 # =============================================================================
 # AUTHENTICATION
 # =============================================================================
diff --git a/portals/api-portal/docs/api-portal-openapi-spec-v0.9.yaml b/portals/api-portal/docs/api-portal-openapi-spec-v0.9.yaml
index 577b30a763..a50a8ae2f8 100644
--- a/portals/api-portal/docs/api-portal-openapi-spec-v0.9.yaml
+++ b/portals/api-portal/docs/api-portal-openapi-spec-v0.9.yaml
@@ -5359,7 +5359,6 @@ components:
       type: object
       required:
         - id
-        - labels
       properties:
         id:
           type: string
@@ -5371,8 +5370,9 @@ components:
           example: Partner APIs
         labels:
           type: array
-          minItems: 1
-          description: Label names to attach to the view.
+          description: >-
+            Label names to attach to the view. Optional — omit or pass an empty array to create a view with no
+            labels, which surfaces no APIs until labels are attached later via the update endpoint.
           items:
             type: string
           example:
diff --git a/portals/api-portal/docs/consume-an-api/consume-with-oauth2.md b/portals/api-portal/docs/consume-an-api/consume-with-oauth2.md
index 55f7433e1e..13fc6f42e5 100644
--- a/portals/api-portal/docs/consume-an-api/consume-with-oauth2.md
+++ b/portals/api-portal/docs/consume-an-api/consume-with-oauth2.md
@@ -76,7 +76,7 @@ curl -X GET "https://api.example.com/orders/v1/orders" \
 
 ## Revoke a Client ID
 
-To remove a linked client ID, go to **Manage Keys** and click **Revoke keys** for that key manager. This only removes the local reference in the portal — it does not deregister or delete the OAuth application in the key manager, and any tokens already issued remain valid until they expire. To invalidate the OAuth application itself or revoke a specific token, use the key manager's own console or revoke endpoint.
+To remove a linked client ID, go to **Manage Keys** and click **Remove keys** for that key manager. This only removes the local reference in the portal — it does not deregister or delete the OAuth application in the key manager, and any tokens already issued remain valid until they expire. To invalidate the OAuth application itself or revoke a specific token, use the key manager's own console or revoke endpoint.
 
 ---
 
diff --git a/portals/api-portal/it/Makefile b/portals/api-portal/it/Makefile
index 1254870c82..a7d7ee7afb 100644
--- a/portals/api-portal/it/Makefile
+++ b/portals/api-portal/it/Makefile
@@ -16,7 +16,9 @@
 # under the License.
 # --------------------------------------------------------------------
 
-.PHONY: all test test-postgres test-rest-api test-rest-api-postgres open clean deps ensure-test-tag ensure-certs
+.PHONY: all test test-postgres test-rest-api test-rest-api-scope test-rest-api-role \
+        test-rest-api-postgres test-rest-api-postgres-scope test-rest-api-postgres-role \
+        open clean deps ensure-test-tag ensure-certs
 
 VERSION ?= $(shell cat ../VERSION 2>/dev/null | tr -d '[:space:]' || echo "0.0.1-SNAPSHOT")
 DOCKER_REGISTRY ?= ghcr.io/wso2/api-platform
@@ -107,19 +109,48 @@ test-postgres: ensure-test-tag ensure-certs
 	docker compose -p $(IT_PROJECT_POSTGRES) -f docker-compose.test.postgres.yaml down -v --remove-orphans; \
 	exit $$EXIT
 
-# Run the REST API integration test suite (Jest + Supertest) against SQLite.
+# --- REST API suite (Jest + Supertest) -------------------------------------
+#
+# The whole suite runs twice, once per authorization mode, because
+# auth.authorization.mode changes where a request's effective scopes come from:
+#
+#   scope — the portal reads the token's own scope claim (what platform-api mints).
+#   role  — the portal IGNORES that claim and expands the token's roles claim
+#           through its own grant table (configs/portal-roles-it.yaml). This is the
+#           SHIPPED DEFAULT in configs/config.toml.
+#
+# Both are real deployment configurations, so both must pass the same specs. The
+# portal-side grant table mirrors platform-api's, which is what lets one set of
+# expectations hold in either mode; auth/grant-table-parity.spec.js guards the mirror
+# and auth/authorization-mode.spec.js covers the deliberate difference between them.
+#
+# `test-rest-api` runs both, sequentially. Use the -scope / -role targets to run one.
 # Requires the API Portal image to be built first: make build (from portals/api-portal/).
-test-rest-api: ensure-test-tag ensure-certs
-	@DOCKER_REGISTRY=$(DOCKER_REGISTRY) docker compose -p $(IT_PROJECT) -f docker-compose.test.yaml up api-portal rest-api-tests --abort-on-container-exit --exit-code-from rest-api-tests; \
+test-rest-api:
+	@$(MAKE) test-rest-api-scope
+	@$(MAKE) test-rest-api-role
+
+test-rest-api-scope: AUTH_MODE = scope
+test-rest-api-role:  AUTH_MODE = role
+test-rest-api-scope test-rest-api-role: ensure-test-tag ensure-certs
+	@echo "==> REST API suite (SQLite, authorization mode = $(AUTH_MODE))"
+	@AUTH_MODE=$(AUTH_MODE) DOCKER_REGISTRY=$(DOCKER_REGISTRY) docker compose -p $(IT_PROJECT) -f docker-compose.test.yaml up api-portal rest-api-tests --abort-on-container-exit --exit-code-from rest-api-tests; \
 	EXIT=$$?; \
-	docker compose -p $(IT_PROJECT) -f docker-compose.test.yaml down -v --remove-orphans; \
+	AUTH_MODE=$(AUTH_MODE) docker compose -p $(IT_PROJECT) -f docker-compose.test.yaml down -v --remove-orphans; \
 	exit $$EXIT
 
-# Run the REST API integration test suite (Jest + Supertest) against PostgreSQL.
-test-rest-api-postgres: ensure-test-tag ensure-certs
-	@DOCKER_REGISTRY=$(DOCKER_REGISTRY) docker compose -p $(IT_PROJECT_POSTGRES) -f docker-compose.test.postgres.yaml up postgres api-portal rest-api-tests --abort-on-container-exit --exit-code-from rest-api-tests; \
+# Same, against PostgreSQL.
+test-rest-api-postgres:
+	@$(MAKE) test-rest-api-postgres-scope
+	@$(MAKE) test-rest-api-postgres-role
+
+test-rest-api-postgres-scope: AUTH_MODE = scope
+test-rest-api-postgres-role:  AUTH_MODE = role
+test-rest-api-postgres-scope test-rest-api-postgres-role: ensure-test-tag ensure-certs
+	@echo "==> REST API suite (PostgreSQL, authorization mode = $(AUTH_MODE))"
+	@AUTH_MODE=$(AUTH_MODE) DOCKER_REGISTRY=$(DOCKER_REGISTRY) docker compose -p $(IT_PROJECT_POSTGRES) -f docker-compose.test.postgres.yaml up postgres api-portal rest-api-tests --abort-on-container-exit --exit-code-from rest-api-tests; \
 	EXIT=$$?; \
-	docker compose -p $(IT_PROJECT_POSTGRES) -f docker-compose.test.postgres.yaml down -v --remove-orphans; \
+	AUTH_MODE=$(AUTH_MODE) docker compose -p $(IT_PROJECT_POSTGRES) -f docker-compose.test.postgres.yaml down -v --remove-orphans; \
 	exit $$EXIT
 
 # Open Cypress interactive UI — runs against a LOCALLY running portal (not in Docker).
diff --git a/portals/api-portal/it/README.md b/portals/api-portal/it/README.md
index 912c570301..b7b69dd4b0 100644
--- a/portals/api-portal/it/README.md
+++ b/portals/api-portal/it/README.md
@@ -45,6 +45,35 @@ Each suite can run against either **SQLite** (default, no external DB) or **Post
 - **Cypress** — UI E2E test framework (headless Electron).
 - **SQLite / PostgreSQL** — SQLite by default; the `-postgres` targets swap in a Postgres service.
 
+## Authorization modes
+
+`auth.authorization.mode` decides where a request's effective scopes come from, and the
+REST suite runs **in full, once per mode**:
+
+| Mode | Effective scopes come from | Grant table |
+|---|---|---|
+| `scope` | the token's own `scope` claim, as minted by platform-api | `configs/roles-platform-api-it.yaml` |
+| `role` (shipped default) | expanding the token's `roles` claim — the scope claim is **ignored** | `configs/portal-roles-it.yaml` |
+
+Both are real deployment configurations, so both must pass the same specs. That works
+because the portal-side table mirrors platform-api's exactly, giving each IT account the
+same grant either way. Two things keep that honest:
+
+- **`rest-api/auth/grant-table-parity.spec.js`** fails if the two tables drift apart,
+  naming the role and the missing scopes — instead of surfacing as a puzzling 403 in
+  some unrelated spec. Regenerate the portal table after editing platform-api's.
+- **`rest-api/auth/authorization-mode.spec.js`** covers the one deliberate divergence.
+  The `narrow` account's roles claim (`dp_narrow_it`) is granted the full developer scope
+  set by platform-api but read-only by the portal, so the *same token* creating an
+  application succeeds in scope mode and is refused in role mode. Each assertion runs in
+  exactly one mode; together they prove the scope claim really is ignored under role mode
+  rather than merged — i.e. a caller cannot widen a role's grant by getting extra scopes
+  from their issuer. No other spec uses that account.
+
+Mode is selected by `AUTH_MODE`, which the compose fixture feeds to both the portal
+(`APIP_AP_AUTH_AUTHORIZATION_MODE`) and the test process (`API_PORTAL_AUTH_MODE`) so they
+cannot disagree. Cypress always runs in the default `scope` mode.
+
 ## Prerequisites
 
 - Docker and Docker Compose
@@ -96,8 +125,12 @@ portals/api-portal/it/
 |---------|-------------|
 | `make test` | Run the Cypress UI suite headlessly (SQLite, CI-friendly) |
 | `make test-postgres` | Run the Cypress UI suite headlessly (PostgreSQL) |
-| `make test-rest-api` | Run the Jest REST API suite (SQLite) |
-| `make test-rest-api-postgres` | Run the Jest REST API suite (PostgreSQL) |
+| `make test-rest-api` | Run the Jest REST API suite (SQLite) — **both** authorization modes, sequentially |
+| `make test-rest-api-scope` | Same, scope mode only |
+| `make test-rest-api-role` | Same, role mode only (the shipped default) |
+| `make test-rest-api-postgres` | Run the Jest REST API suite (PostgreSQL) — both modes |
+| `make test-rest-api-postgres-scope` | Same, scope mode only |
+| `make test-rest-api-postgres-role` | Same, role mode only |
 | `make open` | Open the Cypress interactive UI against a locally running portal |
 | `make deps` | Install Node dependencies (only needed for `make open`) |
 | `make clean` | Remove test containers, volumes, and report artifacts |
@@ -115,8 +148,9 @@ You can also run both UI suites from the portal root: `make -C portals/api-porta
 Both suites run automatically on pull requests that touch `portals/api-portal/**`,
 via [`.github/workflows/devportal-integration-test.yml`](../../../.github/workflows/devportal-integration-test.yml):
 
-- **`rest-api-test`** — builds the image and runs `make test-rest-api` /
-  `make test-rest-api-postgres` in an `sqlite` × `postgres` matrix.
+- **`rest-api-test`** — builds the image and runs the suite in an
+  `sqlite` × `postgres` × `scope` × `role` matrix (four parallel jobs, via the
+  per-mode targets, so covering both authorization modes doesn't double wall-clock).
 - **`ui-test`** — builds the image and runs `make test` (Cypress, SQLite).
 
 Test reports (`it/reports/`) are uploaded as workflow artifacts on every run. The workflow
@@ -134,7 +168,7 @@ Defined in `ui/cypress/support/`:
 |---------|-------------|
 | `cy.visitPortal(path)` | Navigate to a path inside the default portal view |
 | `cy.portalUrl(path)` | Build a URL under the default view without visiting it |
-| `cy.apiRequest(method, path, options)` | `cy.request` wrapper that injects the IT API key header for admin-protected endpoints |
+| `cy.apiRequest(method, path, options)` | `cy.request` wrapper that authenticates with the current session cookie plus the `X-CSRF-Token` header (call `cy.login()` first) |
 | `cy.login(username, password)` | Perform a real login flow (see `support/commands/auth.js`) |
 | `cy.logout()` | Log the current user out |
 | `cy.createApplication(name)` / `cy.deleteApplication(name)` | Create/delete an application (see `support/commands/applications.js`) |
@@ -195,8 +229,10 @@ After a run, artifacts are available under `reports/`:
 - **REST API suite** performs **real session logins** against `platform-api` using the
   file-based users defined in `configs/config-platform-api-it.toml`
   (`admin`/`admin`, `publisher`/`publisher`, `developer`/`developer`).
-- **UI suite** uses both real login flows (`auth/` specs) and, for admin-protected REST
-  calls, an IT API key injected via the `x-wso2-api-key` header.
+- **UI suite** uses real login flows throughout. Seeding and cleanup hooks call
+  `cy.login()` and then `cy.apiRequest`, which authenticates with the resulting session
+  cookie plus the `X-CSRF-Token` double-submit header. `testIsolation` clears cookies
+  between tests, so each `before`/`after` hook needs its own `cy.login()`.
 
 ## Adding New Tests
 
diff --git a/portals/api-portal/it/configs/config-platform-api-it.toml b/portals/api-portal/it/configs/config-platform-api-it.toml
index 7864292ee1..6081c92009 100644
--- a/portals/api-portal/it/configs/config-platform-api-it.toml
+++ b/portals/api-portal/it/configs/config-platform-api-it.toml
@@ -77,3 +77,17 @@ roles         = ["dp_publisher_it"]
 username      = "developer"
 password_hash = "$2y$10$jX3o2E5jF4i3EOgoyJ0k.uegbDYmsmFNDfIxnvcZgTNJifAPjgKKK"
 roles         = ["dp_developer_it"]
+
+# Exists only to make the difference between authorization modes observable.
+#
+# Its roles claim is dp_narrow_it, which platform-api's grant table
+# (roles-platform-api-it.yaml) gives the FULL developer scope set — so the token it
+# receives carries dp:application:create in its scope claim. The portal's own table
+# (portal-roles-it.yaml) grants dp_narrow_it read-only.
+#
+# So this one account can create an application in scope mode and is refused in role
+# mode, which is what auth/authorization-mode.spec.js asserts. No other spec uses it.
+[[platform_api.auth.file.users]]
+username      = "narrow"
+password_hash = "$2b$10$87Aj.eQ6JU4WZ2SohdyZEOKRXfVVt7QPGwE9bwaYxk1WqYbF8uTR6"
+roles         = ["dp_narrow_it"]
diff --git a/portals/api-portal/it/configs/portal-roles-it.yaml b/portals/api-portal/it/configs/portal-roles-it.yaml
new file mode 100644
index 0000000000..dfefcd24bd
--- /dev/null
+++ b/portals/api-portal/it/configs/portal-roles-it.yaml
@@ -0,0 +1,248 @@
+# --------------------------------------------------------------------
+# Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+#
+# WSO2 LLC. licenses this file to you 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
+# --------------------------------------------------------------------
+#
+# The PORTAL-side role-to-scope grant table for the IT fixture
+# (auth.authorization.role_to_scope_mapping). Read ONLY when the suite runs with
+# AUTH_MODE=role; in scope mode the portal reads the token's scope claim instead
+# and never consults this file.
+#
+# Two tables exist because the two components answer different questions:
+#
+#   roles-platform-api-it.yaml  — platform-api's. Expands each IT account's roles
+#                                 into the SCOPE CLAIM of the token it mints.
+#   this file                   — the portal's. In role mode the portal ignores
+#                                 that scope claim and expands the token's ROLES
+#                                 CLAIM through this file instead.
+#
+# The three real accounts are mirrored EXACTLY, so every spec in the suite holds
+# in both modes — that is what lets the whole suite run twice rather than needing
+# a mode-specific set of expectations. auth/grant-table-parity.spec.js fails if
+# the two files ever drift apart, so this is checked rather than hoped for.
+# Regenerate after changing platform-api's table; do not hand-edit these three.
+#
+# dp_narrow_it is the deliberate exception — see its comment below.
+#
+# Every dp:* scope must be declared in docs/api-portal-openapi-spec-v0.9.yaml; the
+# portal validates this file against the spec at startup and refuses to boot on an
+# unknown one, so a typo fails the fixture loudly.
+# --------------------------------------------------------------------
+
+roles:
+  # Mirror of dp_admin_it in roles-platform-api-it.yaml (84 scopes).
+  - name: dp_admin_it
+    scopes:
+      - dp:organization:read
+      - dp:organization:create
+      - dp:organization:update
+      - dp:organization:manage
+      - dp:organization:delete
+      - dp:organization_content:read
+      - dp:organization_content:manage
+      - dp:api:read
+      - dp:api:create
+      - dp:api:update
+      - dp:api:manage
+      - dp:api:delete
+      - dp:api_content:read
+      - dp:api_content:create
+      - dp:api_content:update
+      - dp:api_content:manage
+      - dp:api_content:delete
+      - dp:mcp_server:read
+      - dp:mcp_server:create
+      - dp:mcp_server:update
+      - dp:mcp_server:manage
+      - dp:mcp_server:delete
+      - dp:mcp_server_content:read
+      - dp:mcp_server_content:create
+      - dp:mcp_server_content:update
+      - dp:mcp_server_content:manage
+      - dp:mcp_server_content:delete
+      - dp:api_key:create
+      - dp:api_key:read
+      - dp:api_key:update
+      - dp:api_key:manage
+      - dp:api_key:revoke
+      - dp:mcp_server_key:create
+      - dp:mcp_server_key:read
+      - dp:mcp_server_key:update
+      - dp:mcp_server_key:manage
+      - dp:mcp_server_key:revoke
+      - dp:api_workflow:create
+      - dp:api_workflow:read
+      - dp:api_workflow:update
+      - dp:api_workflow:delete
+      - dp:api_workflow:manage
+      - dp:application:create
+      - dp:application:read
+      - dp:application:update
+      - dp:application:manage
+      - dp:application:delete
+      - dp:application_key:create
+      - dp:application_key:manage
+      - dp:application_key:revoke
+      - dp:application_key_mapping:read
+      - dp:application_key_mapping:create
+      - dp:application_key_mapping:manage
+      - dp:subscription:create
+      - dp:subscription:read
+      - dp:subscription:update
+      - dp:subscription:manage
+      - dp:subscription:delete
+      - dp:subscription_plan:create
+      - dp:subscription_plan:read
+      - dp:subscription_plan:update
+      - dp:subscription_plan:manage
+      - dp:subscription_plan:delete
+      - dp:key_manager:create
+      - dp:key_manager:read
+      - dp:key_manager:update
+      - dp:key_manager:manage
+      - dp:key_manager:delete
+      - dp:view:create
+      - dp:view:read
+      - dp:view:update
+      - dp:view:manage
+      - dp:view:delete
+      - dp:label:create
+      - dp:label:read
+      - dp:label:update
+      - dp:label:manage
+      - dp:label:delete
+      - dp:webhook_subscriber:create
+      - dp:webhook_subscriber:read
+      - dp:webhook_subscriber:update
+      - dp:webhook_subscriber:delete
+      - dp:webhook_subscriber:manage
+      - dp:event:read
+
+  # Mirror of dp_publisher_it in roles-platform-api-it.yaml (62 scopes).
+  - name: dp_publisher_it
+    scopes:
+      - dp:organization:read
+      - dp:api:read
+      - dp:api:create
+      - dp:api:update
+      - dp:api:manage
+      - dp:api:delete
+      - dp:api_content:read
+      - dp:api_content:create
+      - dp:api_content:update
+      - dp:api_content:manage
+      - dp:api_content:delete
+      - dp:mcp_server:read
+      - dp:mcp_server:create
+      - dp:mcp_server:update
+      - dp:mcp_server:manage
+      - dp:mcp_server:delete
+      - dp:mcp_server_content:read
+      - dp:mcp_server_content:create
+      - dp:mcp_server_content:update
+      - dp:mcp_server_content:manage
+      - dp:mcp_server_content:delete
+      - dp:api_key:create
+      - dp:api_key:read
+      - dp:api_key:update
+      - dp:api_key:manage
+      - dp:api_key:revoke
+      - dp:mcp_server_key:create
+      - dp:mcp_server_key:read
+      - dp:mcp_server_key:update
+      - dp:mcp_server_key:manage
+      - dp:mcp_server_key:revoke
+      - dp:api_workflow:create
+      - dp:api_workflow:read
+      - dp:api_workflow:update
+      - dp:api_workflow:delete
+      - dp:api_workflow:manage
+      - dp:subscription_plan:create
+      - dp:subscription_plan:read
+      - dp:subscription_plan:update
+      - dp:subscription_plan:manage
+      - dp:subscription_plan:delete
+      - dp:key_manager:create
+      - dp:key_manager:read
+      - dp:key_manager:update
+      - dp:key_manager:manage
+      - dp:key_manager:delete
+      - dp:view:create
+      - dp:view:read
+      - dp:view:update
+      - dp:view:manage
+      - dp:view:delete
+      - dp:label:create
+      - dp:label:read
+      - dp:label:update
+      - dp:label:manage
+      - dp:label:delete
+      - dp:webhook_subscriber:create
+      - dp:webhook_subscriber:read
+      - dp:webhook_subscriber:update
+      - dp:webhook_subscriber:delete
+      - dp:webhook_subscriber:manage
+      - dp:event:read
+
+  # Mirror of dp_developer_it in roles-platform-api-it.yaml (29 scopes).
+  - name: dp_developer_it
+    scopes:
+      - dp:organization:read
+      - dp:api:read
+      - dp:api_content:read
+      - dp:mcp_server:read
+      - dp:mcp_server_content:read
+      - dp:api_key:create
+      - dp:api_key:read
+      - dp:api_key:update
+      - dp:api_key:manage
+      - dp:api_key:revoke
+      - dp:application:create
+      - dp:application:read
+      - dp:application:update
+      - dp:application:manage
+      - dp:application:delete
+      - dp:application_key:create
+      - dp:application_key:manage
+      - dp:application_key:revoke
+      - dp:application_key_mapping:read
+      - dp:application_key_mapping:create
+      - dp:application_key_mapping:manage
+      - dp:subscription:create
+      - dp:subscription:read
+      - dp:subscription:update
+      - dp:subscription:manage
+      - dp:subscription:delete
+      - dp:subscription_plan:read
+      - dp:view:read
+      - dp:label:read
+
+  # The one role deliberately NOT mirrored, and the only reason this file can
+  # prove anything scope mode cannot.
+  #
+  # platform-api grants dp_narrow_it the full developer scope set, including
+  # dp:application:create — so its token's scope claim permits creating an
+  # application. Here it gets read-only. The same account therefore succeeds in
+  # scope mode and is refused in role mode, which is exactly the assertion pair in
+  # auth/authorization-mode.spec.js: proof that role mode IGNORES the scope claim
+  # rather than merging it, and that a caller cannot widen a role's grant by
+  # obtaining extra scopes from their issuer.
+  #
+  # No other spec uses this account, so the divergence costs the suite nothing.
+  - name: dp_narrow_it
+    scopes:
+      - dp:api:read
+      - dp:api_content:read
+      - dp:mcp_server:read
+      - dp:mcp_server_content:read
+      - dp:organization:read
+      - dp:organization_content:read
+      - dp:subscription_plan:read
+      - dp:view:read
+      - dp:label:read
diff --git a/portals/api-portal/it/configs/roles-platform-api-it.yaml b/portals/api-portal/it/configs/roles-platform-api-it.yaml
index 9a46f31fe5..4f191df0a7 100644
--- a/portals/api-portal/it/configs/roles-platform-api-it.yaml
+++ b/portals/api-portal/it/configs/roles-platform-api-it.yaml
@@ -209,3 +209,40 @@ roles:
       - dp:subscription_plan:read
       - dp:view:read
       - dp:label:read
+
+  # Same grant as dp_developer_it above — deliberately broad HERE so that the
+  # portal-side table (portal-roles-it.yaml), which grants it read-only, visibly
+  # diverges. The gap between the two is what auth/authorization-mode.spec.js reads
+  # to prove role mode ignores the scope claim. Keep these in step with
+  # dp_developer_it; narrowing this one would make the proof vacuous.
+  - name: dp_narrow_it
+    scopes:
+      - dp:organization:read
+      - dp:api:read
+      - dp:api_content:read
+      - dp:mcp_server:read
+      - dp:mcp_server_content:read
+      - dp:api_key:create
+      - dp:api_key:read
+      - dp:api_key:update
+      - dp:api_key:manage
+      - dp:api_key:revoke
+      - dp:application:create
+      - dp:application:read
+      - dp:application:update
+      - dp:application:manage
+      - dp:application:delete
+      - dp:application_key:create
+      - dp:application_key:manage
+      - dp:application_key:revoke
+      - dp:application_key_mapping:read
+      - dp:application_key_mapping:create
+      - dp:application_key_mapping:manage
+      - dp:subscription:create
+      - dp:subscription:read
+      - dp:subscription:update
+      - dp:subscription:manage
+      - dp:subscription:delete
+      - dp:subscription_plan:read
+      - dp:view:read
+      - dp:label:read
diff --git a/portals/api-portal/it/docker-compose.test.postgres.yaml b/portals/api-portal/it/docker-compose.test.postgres.yaml
index 3a86742f98..5f93ac1a9e 100644
--- a/portals/api-portal/it/docker-compose.test.postgres.yaml
+++ b/portals/api-portal/it/docker-compose.test.postgres.yaml
@@ -51,7 +51,7 @@ services:
     # build) instead of the last release — this fixture's config-platform-api-it.toml
     # tracks platform-api's current config schema, which a pinned old release may not
     # understand.
-    image: ${PLATFORM_API_IMAGE:-ghcr.io/wso2/api-platform/platform-api:0.13.0-SNAPSHOT}
+    image: ${PLATFORM_API_IMAGE:-ghcr.io/wso2/api-platform/platform-api:0.14.0-SNAPSHOT}
     command: ["-config", "/etc/platform-api/config-platform-api.toml"]
     environment:
       APIP_CP_ENCRYPTION_KEY: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
@@ -91,6 +91,7 @@ services:
       # Mount only jwt_public.pem, not the whole .certs dir, so the private key
       # (also in .certs, for platform-api) is never exposed to the portal.
       - ./.certs/jwt_public.pem:/etc/api-portal/keys/jwt_public.pem:ro
+      - ./configs/portal-roles-it.yaml:/etc/api-portal/portal-roles-it.yaml:ro
     environment:
       # DB-agnostic settings (tls/logging/api-key/org/platform-api) live in ./test-config.toml.
       APIP_AP_DATABASE_HOST: postgres
@@ -99,6 +100,10 @@ services:
       APIP_AP_DATABASE_USER: api_portal
       APIP_AP_DATABASE_PASSWORD: api_portal
       APIP_AP_DATABASE_NAME: api_portal
+      # Which authorization mode the ENTIRE suite runs against this time — see the
+      # matching note in docker-compose.test.yaml and it/README.md.
+      APIP_AP_AUTH_AUTHORIZATION_MODE: ${AUTH_MODE:-scope}
+      APIP_AP_AUTH_AUTHORIZATION_ROLE_TO_SCOPE_MAPPING: /etc/api-portal/portal-roles-it.yaml
       # portal fails closed at startup without these — fixed test-only values,
       # not meant to be reused outside this CI fixture.
       APIP_AP_SECURITY_ENCRYPTION_KEY: "7f40672c96fd437dc33550755e218d586014232ceb5b01c9405aab575bcb1f4a"
@@ -169,7 +174,6 @@ services:
     shm_size: '2gb'
     environment:
       CYPRESS_BASE_URL: "http://api-portal:9543"
-      CYPRESS_API_KEY: "api-portal-it-test-key"
     volumes:
       - ./ui:/e2e
       - ./reports:/e2e/reports
@@ -195,6 +199,9 @@ services:
       # tokens for. auth/foreign-org-login.spec.js skips itself when this is unset.
       API_PORTAL_OTHER_ORG_BASE_URL: "http://api-portal-other-org:9543"
       API_PORTAL_OTHER_ORG_HANDLE: "other-org"
+      # Must track the portal service's APIP_AP_AUTH_AUTHORIZATION_MODE above;
+      # authorization-mode.spec.js asserts they agree.
+      API_PORTAL_AUTH_MODE: ${AUTH_MODE:-scope}
       API_PORTAL_ORG_HANDLE: "default"
       API_PORTAL_ADMIN_USERNAME: "admin"
       API_PORTAL_ADMIN_PASSWORD: "admin"
@@ -214,6 +221,9 @@ services:
     volumes:
       - ./rest-api:/rest-api
       - ./reports:/rest-api/reports
+      # The two grant tables, for auth/grant-table-parity.spec.js — see the note on
+      # the same mount in docker-compose.test.yaml.
+      - ./configs:/it-configs:ro
     networks:
       - it-api-portal-network
     # better-sqlite3 (an optionalDependency used only by the SQLite variant) is the
diff --git a/portals/api-portal/it/docker-compose.test.yaml b/portals/api-portal/it/docker-compose.test.yaml
index cb50fa7d2b..c5bf27195a 100644
--- a/portals/api-portal/it/docker-compose.test.yaml
+++ b/portals/api-portal/it/docker-compose.test.yaml
@@ -30,7 +30,7 @@ services:
     # build) instead of the last release — this fixture's config-platform-api-it.toml
     # tracks platform-api's current config schema, which a pinned old release may not
     # understand.
-    image: ${PLATFORM_API_IMAGE:-ghcr.io/wso2/api-platform/platform-api:0.13.0-SNAPSHOT}
+    image: ${PLATFORM_API_IMAGE:-ghcr.io/wso2/api-platform/platform-api:0.14.0-SNAPSHOT}
     command: ["-config", "/etc/platform-api/config-platform-api.toml"]
     environment:
       APIP_CP_ENCRYPTION_KEY: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
@@ -65,6 +65,16 @@ services:
       # (tls/logging/api-key/org/platform-api) live in ./test-config.toml.
       APIP_AP_DATABASE_DRIVER: sqlite
       APIP_AP_DATABASE_PATH: /tmp/api-portal-it.db
+      # Which authorization mode the ENTIRE suite runs against this time —
+      # "scope" (default) or "role", selected by the Makefile's
+      # test-rest-api-scope / test-rest-api-role targets. Both modes must pass
+      # the same specs; see it/README.md "Authorization modes".
+      APIP_AP_AUTH_AUTHORIZATION_MODE: ${AUTH_MODE:-scope}
+      # Read only in role mode. Mirrors the scopes platform-api puts in the token's
+      # scope claim, so the two modes grant each IT account the same thing and the
+      # suite's expectations hold either way — grant-table-parity.spec.js fails if
+      # the two tables ever drift apart.
+      APIP_AP_AUTH_AUTHORIZATION_ROLE_TO_SCOPE_MAPPING: /etc/api-portal/portal-roles-it.yaml
       # portal fails closed at startup without these — fixed test-only values,
       # not meant to be reused outside this CI fixture.
       APIP_AP_SECURITY_ENCRYPTION_KEY: "7f40672c96fd437dc33550755e218d586014232ceb5b01c9405aab575bcb1f4a"
@@ -83,6 +93,7 @@ services:
       # Mount only jwt_public.pem, not the whole .certs dir, so the private key
       # (also in .certs, for platform-api) is never exposed to the portal.
       - ./.certs/jwt_public.pem:/etc/api-portal/keys/jwt_public.pem:ro
+      - ./configs/portal-roles-it.yaml:/etc/api-portal/portal-roles-it.yaml:ro
       # Named volume at /tmp (not a new mount point) so Docker copies the image's
       # existing /tmp ownership/permissions into it on first use — a fresh mount
       # at a brand-new path would be root-owned and unwritable by the app user.
@@ -143,7 +154,6 @@ services:
     shm_size: '2gb'
     environment:
       CYPRESS_BASE_URL: "http://api-portal:9543"
-      CYPRESS_API_KEY: "api-portal-it-test-key"
     volumes:
       - ./ui:/e2e
       - ./reports:/e2e/reports
@@ -169,6 +179,11 @@ services:
       # tokens for. auth/foreign-org-login.spec.js skips itself when this is unset.
       API_PORTAL_OTHER_ORG_BASE_URL: "http://api-portal-other-org:9543"
       API_PORTAL_OTHER_ORG_HANDLE: "other-org"
+      # Which authorization mode the portal under test is running. Must track the
+      # portal service's APIP_AP_AUTH_AUTHORIZATION_MODE above — authorization-mode.spec.js
+      # asserts they agree, so a mismatch fails loudly instead of silently testing
+      # the wrong mode.
+      API_PORTAL_AUTH_MODE: ${AUTH_MODE:-scope}
       # Real session login (config-platform-api-it.toml) — password == username
       # for all three, matching the admin/admin convention documented in
       # configs/config-platform-api-template.toml.
@@ -187,6 +202,9 @@ services:
     volumes:
       - ./rest-api:/rest-api
       - ./reports:/rest-api/reports
+      # The two grant tables, so auth/grant-table-parity.spec.js can compare them
+      # directly. Read-only — the suite reads these, the portal and platform-api own them.
+      - ./configs:/it-configs:ro
       # Mounted at a path distinct from this container's own /tmp (needed for
       # npm install), read-only since only the portal process should write it.
       - sqlite-data:/shared-db:ro
diff --git a/portals/api-portal/it/rest-api/ai-discovery/apis-md.spec.js b/portals/api-portal/it/rest-api/ai-discovery/apis-md.spec.js
new file mode 100644
index 0000000000..4816aeae2d
--- /dev/null
+++ b/portals/api-portal/it/rest-api/ai-discovery/apis-md.spec.js
@@ -0,0 +1,67 @@
+// --------------------------------------------------------------------
+// Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+//
+// WSO2 LLC. licenses this file to you 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.
+// --------------------------------------------------------------------
+
+// GET /:orgName/views/:viewName/apis.md — the agent-facing API catalog
+// (src/controllers/apiContentController.js loadAPIsMd). Public agent-discovery
+// route, so client.raw() rather than client.as(role).
+//
+// loadAPIsMd buckets by api.type, which holds the *stored* constant
+// (constants.API_TYPE: REST -> "RestApi", WEBSUB -> "WebSubApi"), not the enum
+// key the buckets are named after. Bucketing on the raw value dropped every
+// REST and WebSub API from this catalog while GraphQL and WebSocket — whose
+// stored value happens to equal the enum key — still showed up, so the
+// regression is invisible unless a REST API is asserted specifically.
+
+const client = require('../support/client');
+const { createApi } = require('../support/fixtures');
+
+describe('AI/LLM discovery (apis.md)', () => {
+    beforeAll(async () => {
+        await client.login('publisher');
+    });
+
+    it('lists a REST API in the catalog', async () => {
+        const api = await createApi({ name: 'Catalogued REST API', type: 'REST', labels: ['default'] });
+
+        const res = await client.raw().get(`/${client.ORG_HANDLE}/views/default/apis.md`);
+        expect(res.status).toBe(200);
+        expect(res.headers['content-type']).toMatch(/text\/markdown/);
+        expect(res.text).toContain(api.name);
+    });
+
+    it('lists a WebSub API in the catalog', async () => {
+        const api = await createApi({ name: 'Catalogued WebSub API', type: 'WEBSUB', labels: ['default'] });
+
+        const res = await client.raw().get(`/${client.ORG_HANDLE}/views/default/apis.md`);
+        expect(res.status).toBe(200);
+        expect(res.text).toContain(api.name);
+    });
+
+    it('excludes APIs with agentVisibility HIDDEN', async () => {
+        const hidden = await createApi({
+            name: 'Hidden REST API',
+            type: 'REST',
+            labels: ['default'],
+            agentVisibility: 'HIDDEN',
+        });
+
+        const res = await client.raw().get(`/${client.ORG_HANDLE}/views/default/apis.md`);
+        expect(res.status).toBe(200);
+        expect(res.text).not.toContain(hidden.name);
+    });
+});
diff --git a/portals/api-portal/it/rest-api/auth/authorization-mode.spec.js b/portals/api-portal/it/rest-api/auth/authorization-mode.spec.js
new file mode 100644
index 0000000000..fe5b2dbc38
--- /dev/null
+++ b/portals/api-portal/it/rest-api/auth/authorization-mode.spec.js
@@ -0,0 +1,130 @@
+// --------------------------------------------------------------------
+// Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+//
+// WSO2 LLC. licenses this file to you 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.
+// --------------------------------------------------------------------
+
+// Where a request's effective scopes come from — auth.authorization.mode.
+//
+//   scope — the portal authorizes against the token's own scope claim.
+//   role  — the portal IGNORES that claim and expands the token's roles claim
+//           through its own grant table instead. This is the shipped default
+//           (configs/config.toml).
+//
+// The whole suite runs once per mode (`make test-rest-api-scope` / `-role`), so every
+// OTHER spec is already a per-mode assertion: they pass unchanged in both because the
+// portal's IT grant table mirrors platform-api's. What this file adds is the part a
+// mirrored table cannot show — that the two modes are genuinely different mechanisms
+// rather than the same one under two names.
+//
+// That is what the `narrow` account is for. platform-api grants dp_narrow_it the full
+// developer scope set, so its token's scope claim permits creating an application; the
+// portal's table grants it read-only. One account, one token, opposite outcomes:
+//
+//   scope mode — create SUCCEEDS (the scope claim is honoured)
+//   role  mode — create is REFUSED (the scope claim is ignored; the role decides)
+//
+// Neither assertion alone proves much. Together they prove the mode switch works, and
+// that a caller cannot widen a role's grant by obtaining extra scopes from their
+// issuer — the security property role mode exists for. Both run in exactly one mode,
+// so each is meaningful where it runs rather than skipped as "not applicable".
+
+const client = require('../support/client');
+
+const MODE = client.AUTH_MODE;
+const ORG = client.ORG_HANDLE;
+const describeScopeMode = MODE === 'scope' ? describe : describe.skip;
+const describeRoleMode = MODE === 'role' ? describe : describe.skip;
+
+const uniq = (prefix) => `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+describe(`authorization mode = ${MODE}`, () => {
+    beforeAll(async () => {
+        await client.login('narrow');
+        await client.login('admin');
+    });
+
+    describe('common to both modes', () => {
+        it('runs against a portal in the mode this run was configured for', async () => {
+            // Guards the whole file. API_PORTAL_AUTH_MODE (this process) and
+            // APIP_AP_AUTH_AUTHORIZATION_MODE (the portal) are set from the same
+            // AUTH_MODE by the compose fixture — if they ever drift, the mode-gated
+            // describes below would silently skip or assert against the wrong mode.
+            expect(['scope', 'role']).toContain(MODE);
+            const res = await client.raw().get(`/${ORG}/views/default`);
+            expect(res.status).toBe(200);
+        });
+
+        it('authorizes an admin operation for the admin account', async () => {
+            // The same grant, reached by two different mechanisms depending on the
+            // mode — mirrored tables are what make this hold either way.
+            const id = uniq('authzmode-label');
+            const res = await client.as('admin').post('/labels', { id, displayName: 'Mode label' });
+            expect(res.status).toBe(201);
+        });
+
+        it('refuses an unauthenticated caller regardless of mode', async () => {
+            const res = await client.raw().get(`${client.API_PREFIX}/organizations/${ORG}`);
+            expect([401, 403]).toContain(res.status);
+        });
+
+        it('lets the narrow account read, in either mode', async () => {
+            // Read is the one thing both its scope claim and its portal-side role
+            // grant permit. Without this, the create assertions below could both be
+            // explained by a broken session rather than by an authorization decision.
+            const res = await client.as('narrow').get('/apis');
+            expect(res.status).toBe(200);
+        });
+    });
+
+    describeScopeMode('scope mode honours the token scope claim', () => {
+        it("lets `narrow` create an application, because its scope claim allows it", async () => {
+            // dp_narrow_it's scope claim carries dp:application:create. The portal's
+            // own grant table says read-only, and in this mode that table is not
+            // consulted at all — so the create succeeds.
+            const res = await client.as('narrow').post('/applications', {
+                displayName: uniq('scopemode-app'),
+                description: 'Permitted by the scope claim',
+            });
+            expect(res.status).toBe(201);
+        });
+    });
+
+    describeRoleMode('role mode ignores the token scope claim', () => {
+        it("refuses `narrow` the same create, because its ROLE grants no application scope", async () => {
+            // Same account, same token, same scope claim as the scope-mode case above.
+            // Only the portal's interpretation differs. A 403 here is only meaningful
+            // because the scope-mode run asserts 201 for the identical call.
+            const res = await client.as('narrow').post('/applications', {
+                displayName: uniq('rolemode-app'),
+                description: 'Must be refused — the role grants no application scope',
+            });
+            expect(res.status).toBe(403);
+        });
+
+        it('refuses a key-manager read to the narrow role', async () => {
+            const res = await client.as('narrow').get('/key-managers');
+            expect(res.status).toBe(403);
+        });
+
+        it('expands a role into scopes rather than denying everything', async () => {
+            // The counterweight to the two denials: role expansion is granting real
+            // access, not failing closed across the board. Without it, both denials
+            // above would also pass if role mode were simply broken.
+            const res = await client.as('admin').get('/key-managers');
+            expect(res.status).toBe(200);
+        });
+    });
+});
diff --git a/portals/api-portal/it/rest-api/auth/grant-table-parity.spec.js b/portals/api-portal/it/rest-api/auth/grant-table-parity.spec.js
new file mode 100644
index 0000000000..f2a8b1b59f
--- /dev/null
+++ b/portals/api-portal/it/rest-api/auth/grant-table-parity.spec.js
@@ -0,0 +1,83 @@
+// --------------------------------------------------------------------
+// Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+//
+// WSO2 LLC. licenses this file to you 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.
+// --------------------------------------------------------------------
+
+// Keeps the two IT grant tables in step.
+//
+// The whole suite runs in both authorization modes against ONE set of expectations,
+// which only works because each IT account is granted the same thing either way:
+//
+//   scope mode — platform-api expands the account's roles into the token's scope claim
+//                (configs/roles-platform-api-it.yaml)
+//   role  mode — the portal expands the same roles through its own table
+//                (configs/portal-roles-it.yaml)
+//
+// Two files, so they can drift. The failure that drift causes is nasty: add a scope to
+// platform-api's table for a new endpoint's tests, and the scope-mode run goes green
+// while the role-mode run fails somewhere unrelated-looking, with a 403 that points at
+// the endpoint rather than at the table. This spec turns that into one obvious failure
+// naming the role and the missing scopes.
+//
+// No HTTP — it reads the two fixture files directly, so it costs nothing and reports
+// the same way in both modes.
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// Mounted at /it-configs in the test container (the repo's it/configs is outside
+// the /rest-api mount); the relative path is the fallback for a host-side run.
+const CONFIGS = process.env.IT_CONFIGS_DIR
+    || (fs.existsSync('/it-configs') ? '/it-configs' : path.join(__dirname, '..', '..', 'configs'));
+
+// Deliberately divergent — see the comments in both files. This is the one role whose
+// portal-side grant is narrower than its scope claim, which is what makes the
+// mode difference observable in authorization-mode.spec.js.
+const INTENTIONALLY_DIVERGENT = new Set(['dp_narrow_it']);
+
+function loadRoles(file) {
+    const doc = yaml.load(fs.readFileSync(path.join(CONFIGS, file), 'utf8'));
+    return new Map((doc.roles || []).map((r) => [r.name, [...r.scopes].sort()]));
+}
+
+describe('IT grant tables', () => {
+    const platformApi = loadRoles('roles-platform-api-it.yaml');
+    const portal = loadRoles('portal-roles-it.yaml');
+    const shared = [...platformApi.keys()].filter((r) => !INTENTIONALLY_DIVERGENT.has(r));
+
+    it('define the same roles on both sides', () => {
+        expect(shared.length).toBeGreaterThan(0); // guards against an empty-file false pass
+        expect([...portal.keys()].sort()).toEqual([...platformApi.keys()].sort());
+    });
+
+    it.each(shared)('grant %s identical scopes on both sides', (role) => {
+        // Fails as a readable scope diff naming the role, rather than as a 403 in
+        // whichever unrelated spec happened to need the missing scope first.
+        expect(portal.get(role)).toEqual(platformApi.get(role));
+    });
+
+    it('keeps dp_narrow_it deliberately narrower on the portal side', () => {
+        // The divergence is load-bearing, so assert it rather than merely excluding
+        // it: if someone "fixes" the mirror by syncing this role too, the scope-claim-
+        // is-ignored proof in authorization-mode.spec.js silently stops proving it.
+        const paScopes = platformApi.get('dp_narrow_it');
+        const portalScopes = portal.get('dp_narrow_it');
+        expect(paScopes).toContain('dp:application:create');
+        expect(portalScopes).not.toContain('dp:application:create');
+        expect(portalScopes.every((s) => s.endsWith(':read'))).toBe(true);
+    });
+});
diff --git a/portals/api-portal/it/rest-api/organizations/single-org-isolation.spec.js b/portals/api-portal/it/rest-api/organizations/single-org-isolation.spec.js
index 960813fb44..6c73c9d3b7 100644
--- a/portals/api-portal/it/rest-api/organizations/single-org-isolation.spec.js
+++ b/portals/api-portal/it/rest-api/organizations/single-org-isolation.spec.js
@@ -21,18 +21,22 @@
 // accept one must reject anything but this instance's own organization:
 //
 //   page URLs            /{orgHandle}/...            -> 404   (src/middlewares/orgGuard.js)
-//   `organization` header on an API-key request      -> 403   (src/middlewares/authMiddleware.js)
 //
-// These are all unauthenticated or API-key surfaces — the point is that no
-// credential is needed to attempt them, so the rejection cannot depend on one.
-// Token/session organization claims are covered by auth/file-based-login.spec.js.
+// The page surfaces are unauthenticated — the point is that no credential is
+// needed to attempt them, so the rejection cannot depend on one.
+//
+// authMiddleware's `organization` header check (resolvePortalOrg -> 403) now only
+// applies to mTLS, the sole remaining credential that carries no organization of
+// its own; the static service API key that used to reach it was removed, and this
+// fixture provisions no client certificates, so that path is not exercised here.
+// For session and bearer credentials the organization comes from the credential's
+// own claim (resolveScopedOrg) and the header is never a selector — asserted
+// below, and covered further by auth/file-based-login.spec.js.
 
 const client = require('../support/client');
 
 const OWN_ORG = client.ORG_HANDLE;
 const FOREIGN_ORG = 'some-other-org';
-const API_KEY_HEADER = 'x-wso2-api-key';
-const API_KEY = process.env.API_PORTAL_API_KEY || 'api-portal-it-test-key';
 
 describe('single-organization isolation', () => {
     describe('page routes', () => {
@@ -71,31 +75,31 @@ describe('single-organization isolation', () => {
         });
     });
 
-    describe('organization request header', () => {
-        it('scopes an API-key request to this organization when no header is sent', async () => {
-            const res = await client.raw()
-                .get(`${client.API_PREFIX}/apis`)
-                .set(API_KEY_HEADER, API_KEY);
+    describe('organization request header on a session credential', () => {
+        beforeAll(async () => {
+            await client.login('admin');
+        });
+
+        it('serves the caller organization when no header is sent', async () => {
+            const res = await client.as('admin').get('/apis');
             expect(res.status).toBe(200);
         });
 
-        it('accepts a header naming this organization', async () => {
-            const res = await client.raw()
-                .get(`${client.API_PREFIX}/apis`)
-                .set(API_KEY_HEADER, API_KEY)
-                .set('organization', OWN_ORG);
+        it('serves the caller organization when the header names it', async () => {
+            const res = await client.as('admin').get('/apis').set('organization', OWN_ORG);
             expect(res.status).toBe(200);
         });
 
-        it('rejects a header naming another organization with 403', async () => {
-            // Honouring this header would make one API key able to address every
-            // tenant in the shared database. Rejecting rather than ignoring it also
-            // keeps a caller from believing it wrote to the organization it named.
-            const res = await client.raw()
-                .get(`${client.API_PREFIX}/apis`)
-                .set(API_KEY_HEADER, API_KEY)
-                .set('organization', FOREIGN_ORG);
-            expect(res.status).toBe(403);
+        it('does not let the header redirect the request to another organization', async () => {
+            // The organization comes from the session's own claim, so this header is
+            // not a selector. Honouring it would let one credential address every
+            // tenant in the shared database; the request must stay scoped to the
+            // caller's organization rather than reaching the one it named.
+            const res = await client.as('admin').get('/apis').set('organization', FOREIGN_ORG);
+            expect(res.status).toBe(200);
+
+            const own = await client.as('admin').get('/apis');
+            expect(res.body).toEqual(own.body);
         });
     });
 
diff --git a/portals/api-portal/it/rest-api/package-lock.json b/portals/api-portal/it/rest-api/package-lock.json
index 27ac2b0a80..e7c4a93330 100644
--- a/portals/api-portal/it/rest-api/package-lock.json
+++ b/portals/api-portal/it/rest-api/package-lock.json
@@ -11,6 +11,7 @@
         "cookiejar": "2.1.4",
         "jest": "29.7.0",
         "jest-junit": "17.0.0",
+        "js-yaml": "5.2.3",
         "nock": "13.5.6",
         "pg": "8.22.0",
         "supertest": "7.2.2"
@@ -532,6 +533,30 @@
         "node": ">=8"
       }
     },
+    "node_modules/@istanbuljs/load-nyc-config/node_modules/argparse": {
+      "version": "1.0.10",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
+      "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "sprintf-js": "~1.0.2"
+      }
+    },
+    "node_modules/@istanbuljs/load-nyc-config/node_modules/js-yaml": {
+      "version": "3.15.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.1.tgz",
+      "integrity": "sha512-S99WuO3HlhO3XN41EtYUNl9zzXjoJx7QvmipxsJVxtCBT0YHEFy+iOJhjSvrmV12nYhWpZaM8lPHkJm0yUMbag==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^1.0.7",
+        "esprima": "^4.0.0"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
     "node_modules/@istanbuljs/schema": {
       "version": "0.1.6",
       "resolved": "https://registry.npmjs.org/@istanbuljs/schema/-/schema-0.1.6.tgz",
@@ -1107,14 +1132,11 @@
       }
     },
     "node_modules/argparse": {
-      "version": "1.0.10",
-      "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
-      "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
       "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "sprintf-js": "~1.0.2"
-      }
+      "license": "Python-2.0"
     },
     "node_modules/asap": {
       "version": "2.0.6",
@@ -3208,17 +3230,26 @@
       "license": "MIT"
     },
     "node_modules/js-yaml": {
-      "version": "3.15.0",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.0.tgz",
-      "integrity": "sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==",
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-5.2.3.tgz",
+      "integrity": "sha512-n+mUVyUX5bVv7G/G2zyIHOhdxfuU1dY2NOFzTQUWiMUbFss8b57NFlgCCaggU78wSw5KVS9cllzeLyzyR+n5nw==",
       "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
       "license": "MIT",
       "dependencies": {
-        "argparse": "^1.0.7",
-        "esprima": "^4.0.0"
+        "argparse": "^2.0.1"
       },
       "bin": {
-        "js-yaml": "bin/js-yaml.js"
+        "js-yaml": "bin/js-yaml.mjs"
       }
     },
     "node_modules/jsesc": {
diff --git a/portals/api-portal/it/rest-api/package.json b/portals/api-portal/it/rest-api/package.json
index 03d4811a46..41ac97b3e9 100644
--- a/portals/api-portal/it/rest-api/package.json
+++ b/portals/api-portal/it/rest-api/package.json
@@ -11,6 +11,7 @@
     "cookiejar": "2.1.4",
     "jest": "29.7.0",
     "jest-junit": "17.0.0",
+    "js-yaml": "5.2.3",
     "nock": "13.5.6",
     "pg": "8.22.0",
     "supertest": "7.2.2"
diff --git a/portals/api-portal/it/rest-api/support/client.js b/portals/api-portal/it/rest-api/support/client.js
index e06093e352..c38b386931 100644
--- a/portals/api-portal/it/rest-api/support/client.js
+++ b/portals/api-portal/it/rest-api/support/client.js
@@ -42,8 +42,18 @@ const CREDENTIALS = {
     admin: { username: process.env.API_PORTAL_ADMIN_USERNAME || 'admin', password: process.env.API_PORTAL_ADMIN_PASSWORD || 'admin' },
     publisher: { username: process.env.API_PORTAL_PUBLISHER_USERNAME || 'publisher', password: process.env.API_PORTAL_PUBLISHER_PASSWORD || 'publisher' },
     developer: { username: process.env.API_PORTAL_DEVELOPER_USERNAME || 'developer', password: process.env.API_PORTAL_DEVELOPER_PASSWORD || 'developer' },
+    // Used by auth/authorization-mode.spec.js only. Its portal-side grant is
+    // deliberately narrower than its token's scope claim, which is what makes the
+    // scope-mode/role-mode difference observable. Don't reach for it in other specs —
+    // what it can do depends on which mode the run is in.
+    narrow: { username: process.env.API_PORTAL_NARROW_USERNAME || 'narrow', password: process.env.API_PORTAL_NARROW_PASSWORD || 'narrow' },
 };
 
+// Which authorization mode the portal under test is running ("scope" | "role"),
+// set by the compose fixture from the Makefile's AUTH_MODE. Specs whose expectations
+// differ per mode branch on this; everything else must pass in both.
+const AUTH_MODE = process.env.API_PORTAL_AUTH_MODE || 'scope';
+
 // One supertest agent per role, logged in once and reused — the agent's cookie
 // jar carries the session across every request made through it.
 const agents = {};
@@ -144,6 +154,7 @@ module.exports = {
     BASE_URL,
     API_PREFIX,
     ORG_HANDLE,
+    AUTH_MODE,
     login,
     as,
     page,
diff --git a/portals/api-portal/it/rest-api/support/fixtures.js b/portals/api-portal/it/rest-api/support/fixtures.js
index 956f8adedb..ced8bedb32 100644
--- a/portals/api-portal/it/rest-api/support/fixtures.js
+++ b/portals/api-portal/it/rest-api/support/fixtures.js
@@ -98,8 +98,9 @@ async function createApi(overrides = {}) {
 }
 
 // `admin` manages org-level integration config; pass `role` to override.
-// displayName is required by WebhookSubscriberRequest (the settings UI collects a
-// name, not a handle, and the handle is generated from it when `id` is omitted).
+// displayName is required by WebhookSubscriberRequest; `id` (the handle) is
+// optional here — the server generates a UUID when it is omitted, which is what
+// these fixtures rely on. The settings UI collects both explicitly.
 async function createWebhookSubscriber(overrides = {}) {
     const { role = 'admin', ...bodyOverrides } = overrides;
     const res = await client.as(role).post('/webhook-subscribers', {
diff --git a/portals/api-portal/it/rest-api/views-and-labels/views.spec.js b/portals/api-portal/it/rest-api/views-and-labels/views.spec.js
index be1092a987..215889aa72 100644
--- a/portals/api-portal/it/rest-api/views-and-labels/views.spec.js
+++ b/portals/api-portal/it/rest-api/views-and-labels/views.spec.js
@@ -17,7 +17,8 @@
 // --------------------------------------------------------------------
 
 // POST/GET/PUT/DELETE /views. A view groups a set of labels to filter which
-// APIs are visible in that portal view. ViewCreateRequest requires { id, labels }.
+// APIs are visible in that portal view. ViewCreateRequest requires only { id } —
+// labels are optional, so a view can be created first and labelled later.
 // `admin` manages org-level config.
 
 const client = require('../support/client');
@@ -49,6 +50,28 @@ describe('views', () => {
         expect(res.status).toBe(201);
     });
 
+    it('creates a view with no labels', async () => {
+        const id = uniqueHandle('view');
+        const res = await client.as('admin').post('/views', { id, displayName: 'Unlabelled View' });
+        expect(res.status).toBe(201);
+
+        const fetched = await client.as('admin').get(`/views/${id}`);
+        expect(fetched.status).toBe(200);
+        expect(fetched.body.labels).toEqual([]);
+    });
+
+    it('creates a view with an empty label array', async () => {
+        const id = uniqueHandle('view');
+        const res = await client.as('admin').post('/views', { id, displayName: 'Empty Labels View', labels: [] });
+        expect(res.status).toBe(201);
+
+        // Read back, as the omitted-labels case above does: an explicit [] has to
+        // persist as no associations, not merely be accepted by the create.
+        const fetched = await client.as('admin').get(`/views/${id}`);
+        expect(fetched.status).toBe(200);
+        expect(fetched.body.labels).toEqual([]);
+    });
+
     it('retrieves a view', async () => {
         const id = uniqueHandle('view');
         await client.as('admin').post('/views', { id, displayName: 'Retrievable View', labels: [label.id] });
diff --git a/portals/api-portal/it/test-config.toml b/portals/api-portal/it/test-config.toml
index 73e7d02888..a290f4abf8 100644
--- a/portals/api-portal/it/test-config.toml
+++ b/portals/api-portal/it/test-config.toml
@@ -38,10 +38,6 @@ name     = '{{ env "APIP_AP_DATABASE_NAME" "api_portal" }}'
 encryption_key = '{{ env "APIP_AP_SECURITY_ENCRYPTION_KEY" }}'
 session_secret = '{{ env "APIP_AP_SECURITY_SESSION_SECRET" }}'
 
-[api_portal.security.service_api_key]
-enabled = true
-value = "api-portal-it-test-key"
-
 [api_portal.organization]
 # The single organization each portal instance serves. Tokenized because the
 # fixture runs a SECOND instance (api-portal-other-org) off this same file with a
@@ -51,14 +47,25 @@ handle       = '{{ env "APIP_AP_ORGANIZATION_HANDLE" "default" }}'
 display_name = '{{ env "APIP_AP_ORGANIZATION_DISPLAY_NAME" "Default" }}'
 auto_create_subscription_plans = true
 
-# The IT suite authorizes against the dp:* scopes the Platform API sidecar mints into
-# each token's scope claim — its own grant table (configs/roles-platform-api-it.yaml)
+# Most of the suite authorizes against the dp:* scopes the Platform API sidecar mints
+# into each token's scope claim — its own grant table (configs/roles-platform-api-it.yaml)
 # is where the three IT accounts' privileges are defined. That is scope mode by
-# definition, so it is pinned here rather than inheriting the "role" default: role mode
-# would expand the dp_*_it role names against the PORTAL's grant table, which does not
-# define them, and every REST assertion would 403.
+# definition, so it is the default here rather than the shipped "role": role mode would
+# expand the dp_*_it role names against the PORTAL's grant table, and the table baked
+# into the image does not define them, so every REST assertion would 403.
+#
+# Tokenized, not hardcoded, because the fixture also runs a THIRD portal instance
+# (api-portal-role-mode) off this same file with mode = "role" and a grant table that
+# does define those roles (configs/portal-roles-role-mode-it.yaml) — role mode is the
+# shipped default in configs/config.toml, so leaving it unexercised meant the suite
+# never covered the configuration most deployments actually run. Driven by
+# rest-api/auth/role-mode-authorization.spec.js.
 [api_portal.auth.authorization]
-mode = "scope"
+mode = '{{ env "APIP_AP_AUTH_AUTHORIZATION_MODE" "scope" }}'
+# Only read in role mode. The default points at the copy baked into the image so the
+# scope-mode instances resolve a real path; the role-mode instance overrides it with
+# its mounted IT table.
+role_to_scope_mapping = '{{ env "APIP_AP_AUTH_AUTHORIZATION_ROLE_TO_SCOPE_MAPPING" "./resources/role-to-scope-mapping.yaml" }}'
 
 [api_portal.auth.local]
 # File-based (local) auth against the Platform API sidecar. Host is identical in
diff --git a/portals/api-portal/it/ui/cypress/e2e/001-basic/001-portal-access.cy.js b/portals/api-portal/it/ui/cypress/e2e/001-basic/001-portal-access.cy.js
index 79249ccc98..424136de44 100644
--- a/portals/api-portal/it/ui/cypress/e2e/001-basic/001-portal-access.cy.js
+++ b/portals/api-portal/it/ui/cypress/e2e/001-basic/001-portal-access.cy.js
@@ -27,11 +27,15 @@ describe('API Portal — Portal Access', () => {
     let mcpHandle;
 
     before(() => {
+        // Seeding goes through the REST API as a logged-in admin — the portal's
+        // static service API key is gone.
+        cy.login();
         cy.seedApi().then((handle) => { apiHandle = handle; });
         cy.seedMcp().then((handle) => { mcpHandle = handle; });
     });
 
     after(() => {
+        cy.login();
         cy.deleteApi(apiHandle);
         cy.deleteMcp(mcpHandle);
     });
diff --git a/portals/api-portal/it/ui/cypress/e2e/002-apis/001-api-listing.cy.js b/portals/api-portal/it/ui/cypress/e2e/002-apis/001-api-listing.cy.js
index 14ce730bf9..1e6e81d46f 100644
--- a/portals/api-portal/it/ui/cypress/e2e/002-apis/001-api-listing.cy.js
+++ b/portals/api-portal/it/ui/cypress/e2e/002-apis/001-api-listing.cy.js
@@ -29,6 +29,7 @@ describe('API listing', () => {
     let mcpHandle;
 
     before(() => {
+        cy.login();
         // Seed two APIs of different types so the listing shows distinct badges,
         // plus an MCP server — which must NOT appear on the /apis listing (it
         // belongs on /mcps). loadAPIs filters type !== MCP for the APIs page.
@@ -44,6 +45,7 @@ describe('API listing', () => {
     });
 
     after(() => {
+        cy.login();
         cy.deleteApi(restHandle);
         cy.deleteApi(gqlHandle);
         cy.deleteMcp(mcpHandle);
diff --git a/portals/api-portal/it/ui/cypress/e2e/002-apis/002-rest-api-details.cy.js b/portals/api-portal/it/ui/cypress/e2e/002-apis/002-rest-api-details.cy.js
index f8461e462d..0d91d464bd 100644
--- a/portals/api-portal/it/ui/cypress/e2e/002-apis/002-rest-api-details.cy.js
+++ b/portals/api-portal/it/ui/cypress/e2e/002-apis/002-rest-api-details.cy.js
@@ -26,6 +26,7 @@ describe('REST API — overview, documentation & try-out', () => {
     let apiHandle;
 
     before(() => {
+        cy.login();
         cy.seedApi({
             name: API_NAME,
             version: 'v1.0',
@@ -67,6 +68,7 @@ describe('REST API — overview, documentation & try-out', () => {
     });
 
     after(() => {
+        cy.login();
         cy.deleteApi(apiHandle);
     });
 
diff --git a/portals/api-portal/it/ui/cypress/e2e/003-mcp-servers/001-mcp-listing.cy.js b/portals/api-portal/it/ui/cypress/e2e/003-mcp-servers/001-mcp-listing.cy.js
index 24b956747b..535c6ba634 100644
--- a/portals/api-portal/it/ui/cypress/e2e/003-mcp-servers/001-mcp-listing.cy.js
+++ b/portals/api-portal/it/ui/cypress/e2e/003-mcp-servers/001-mcp-listing.cy.js
@@ -30,6 +30,7 @@ describe('MCP server listing', () => {
     let restHandle;
 
     before(() => {
+        cy.login();
         cy.seedMcp({ name: MCP_ONE }).then((h) => { mcpOneHandle = h; });
         cy.seedMcp({ name: MCP_TWO }).then((h) => { mcpTwoHandle = h; });
         // A REST API — must NOT appear on the /mcps listing (it belongs on /apis).
@@ -37,6 +38,7 @@ describe('MCP server listing', () => {
     });
 
     after(() => {
+        cy.login();
         cy.deleteMcp(mcpOneHandle);
         cy.deleteMcp(mcpTwoHandle);
         cy.deleteApi(restHandle);
diff --git a/portals/api-portal/it/ui/cypress/e2e/applications/application-flows.cy.js b/portals/api-portal/it/ui/cypress/e2e/applications/application-flows.cy.js
index 9c98bb5095..0adef3f2b0 100644
--- a/portals/api-portal/it/ui/cypress/e2e/applications/application-flows.cy.js
+++ b/portals/api-portal/it/ui/cypress/e2e/applications/application-flows.cy.js
@@ -100,6 +100,9 @@ describe('Applications', () => {
         let mockToken;
 
         before(() => {
+            // Key managers are admin-only over the REST API, and seeding now
+            // authenticates with a session rather than the removed service API key.
+            cy.login();
             // Start the mock OAuth2 token endpoint only for this context, and point
             // the key manager at it so the token round-trip can actually resolve.
             cy.task('startMockTokenServer').then((mock) => {
@@ -113,6 +116,7 @@ describe('Applications', () => {
         });
 
         after(() => {
+            cy.login();
             cy.deleteKeyManager(KM_ID);
             cy.task('stopMockTokenServer');
         });
diff --git a/portals/api-portal/it/ui/cypress/e2e/settings/001-views-labels.cy.js b/portals/api-portal/it/ui/cypress/e2e/settings/001-views-labels.cy.js
index 000bc01703..409c2fdb02 100644
--- a/portals/api-portal/it/ui/cypress/e2e/settings/001-views-labels.cy.js
+++ b/portals/api-portal/it/ui/cypress/e2e/settings/001-views-labels.cy.js
@@ -28,9 +28,9 @@ describe('Settings — Views & Labels', () => {
     const VIEW_HANDLE = `it-view-${uid}`; // slugify(VIEW_NAME)
     const LABEL_DISPLAY = `IT Label ${uid}`;
     const LABEL_HANDLE = `it-label-${uid}`; // slugify(LABEL_DISPLAY)
-    // A view requires at least one label (ViewCreateRequest.labels has minItems: 1), so
-    // the view test needs an existing label to pick. Seed one up front, distinct from the
-    // label the label test creates.
+    // Labels are optional on a view, but this test exercises attaching one from the
+    // picker, so it needs an existing label to click. Seed one up front, distinct from
+    // the label the label test creates.
     const VIEW_LABEL = `it-vlabel-${uid}`;
 
     const settingsUrl = () => `/${Cypress.env('ORG_HANDLE')}/settings`;
@@ -42,6 +42,7 @@ describe('Settings — Views & Labels', () => {
 
     after(() => {
         // Robust API cleanup, idempotent (404 if the create step never persisted).
+        cy.login();
         cy.apiRequest('DELETE', `/api/v0.9/views/${VIEW_HANDLE}`, { failOnStatusCode: false });
         cy.apiRequest('DELETE', `/api/v0.9/labels/${LABEL_HANDLE}`, { failOnStatusCode: false });
         cy.apiRequest('DELETE', `/api/v0.9/labels/${VIEW_LABEL}`, { failOnStatusCode: false });
diff --git a/portals/api-portal/it/ui/cypress/e2e/settings/002-key-managers.cy.js b/portals/api-portal/it/ui/cypress/e2e/settings/002-key-managers.cy.js
index 29c3ad191a..d48ce233f3 100644
--- a/portals/api-portal/it/ui/cypress/e2e/settings/002-key-managers.cy.js
+++ b/portals/api-portal/it/ui/cypress/e2e/settings/002-key-managers.cy.js
@@ -37,11 +37,12 @@ describe('Settings — Key Managers', () => {
         cy.clearCookies();
         cy.login('developer', 'developer');
         cy.deleteApplication(APP_NAME);
-        // Then the key manager. Clear the developer session so this authorizes via the
-        // admin API key (x-wso2-api-key) — with the developer session still set, the
-        // server would authorize as `developer`, who lacks dp:key_manager:read, and return 403.
+        // Then the key manager. Swap the developer session for an admin one — the
+        // REST call authorizes as whoever is logged in, and `developer` lacks
+        // dp:key_manager:read, so it would 403.
         // The handle is a server-generated UUID, so discover it by display name.
         cy.clearCookies();
+        cy.login();
         cy.apiRequest('GET', '/api/v0.9/key-managers').then((res) => {
             (res.body.list || [])
                 .filter((km) => km.displayName === KM_NAME)
diff --git a/portals/api-portal/it/ui/cypress/support/commands/portal.js b/portals/api-portal/it/ui/cypress/support/commands/portal.js
index a98b18ef15..df24bd2d88 100644
--- a/portals/api-portal/it/ui/cypress/support/commands/portal.js
+++ b/portals/api-portal/it/ui/cypress/support/commands/portal.js
@@ -30,21 +30,28 @@ Cypress.Commands.add('portalUrl', (path = '') => {
 
 // ---------------------------------------------------------------------------
 // cy.apiRequest(method, path, options)
-//   Thin wrapper around cy.request that includes the API key header for
-//   accessing admin-protected portal endpoints in the IT environment.
+//   Call a portal REST endpoint as whichever user is currently logged in.
+//
+//   The portal's static service API key (x-wso2-api-key) was removed, so these
+//   calls authenticate with the ordinary session cookie — cy.request shares the
+//   browser's cookie jar — plus the X-CSRF-Token header that csrfProtection
+//   requires on mutating cookie-authenticated requests (double-submit of the
+//   XSRF-TOKEN cookie the server sets on every response).
+//
+//   Callers must have established a session first: testIsolation clears cookies
+//   between tests, so before()/after() hooks need their own cy.login().
 // ---------------------------------------------------------------------------
 Cypress.Commands.add('apiRequest', (method, path, options = {}) => {
-    const apiKey = Cypress.env('API_KEY');
-    const headers = apiKey
-        ? { 'x-wso2-api-key': apiKey, ...(options.headers || {}) }
-        : (options.headers || {});
-    return cy.request({
+    return cy.getCookie('XSRF-TOKEN').then((csrf) => cy.request({
         method,
         url: path,
         failOnStatusCode: options.failOnStatusCode !== false,
         ...options,
-        headers,
-    });
+        headers: {
+            ...(csrf && csrf.value ? { 'X-CSRF-Token': decodeURIComponent(csrf.value) } : {}),
+            ...(options.headers || {}),
+        },
+    }));
 });
 
 // ---------------------------------------------------------------------------
diff --git a/portals/api-portal/it/ui/cypress/support/commands/seed.js b/portals/api-portal/it/ui/cypress/support/commands/seed.js
index 1b767a6693..451d2e0677 100644
--- a/portals/api-portal/it/ui/cypress/support/commands/seed.js
+++ b/portals/api-portal/it/ui/cypress/support/commands/seed.js
@@ -19,11 +19,12 @@
 // ---------------------------------------------------------------------------
 // Seed helpers — create demo REST APIs / MCP servers through the real portal
 // management API (POST /api/v0.9/apis, /mcp-servers) so UI browse tests have
-// something to render. They go through cy.apiRequest, which injects the
-// service API-key header; the `organization` header selects the target org
-// (authMiddleware.resolveOrgFromHeader), and `labels: ['default']` maps the
-// resource into the default view so it appears on the /apis and /mcps listings
-// (apiDao.list requires a label mapped to the view).
+// something to render. They go through cy.apiRequest, which authenticates with
+// the caller's session cookie — so the calling hook must cy.login() first. The
+// `organization` header names the target org (authMiddleware.resolvePortalOrg
+// rejects any other), and `labels: ['default']` maps the resource into the
+// default view so it appears on the /apis and /mcps listings (apiDao.list
+// requires a label mapped to the view).
 //
 // These endpoints take multipart/form-data. cy.request runs in Node, not the
 // browser, so a browser FormData won't serialize — instead we build the
@@ -50,7 +51,7 @@ function buildMultipart(parts) {
 
 function seedHeaders(contentType) {
     return {
-        // authMiddleware resolves the target org from this header for API-key requests.
+        // Checked against the organization this instance serves; a mismatch is a 403.
         organization: Cypress.env('ORG_HANDLE'),
         'content-type': contentType,
     };
diff --git a/portals/api-portal/src/config/configDefaults.js b/portals/api-portal/src/config/configDefaults.js
index e07c45ffe8..05602b315e 100644
--- a/portals/api-portal/src/config/configDefaults.js
+++ b/portals/api-portal/src/config/configDefaults.js
@@ -75,11 +75,6 @@ const DEFAULTS = {
     security: {
         encryptionKey: '',
         sessionSecret: '',
-        serviceApiKey: {
-            enabled: true,
-            headerName: 'x-wso2-api-key',
-            value: '',
-        },
     },
     // Authentication — HOW a token is verified: a mode gate plus the two backends it
     // selects between, local (default) and idp. What a verified token may DO is
diff --git a/portals/api-portal/src/controllers/apiContentController.js b/portals/api-portal/src/controllers/apiContentController.js
index 43ab8048f8..1e9eb08c38 100644
--- a/portals/api-portal/src/controllers/apiContentController.js
+++ b/portals/api-portal/src/controllers/apiContentController.js
@@ -145,7 +145,7 @@ const loadAPIs = async (req, res, next) => {
                 const err = Object.assign(new Error(constants.ERROR_MESSAGE.COMMON_AUTH_ERROR_MESSAGE), { status: 401 });
                 return next(err);
             } else {
-                error.status = 500;
+                error.status = util.pageErrorStatus(error);
                 return next(error);
             }
         }
@@ -436,7 +436,7 @@ const loadAPIContent = async (req, res, next) => {
                 const err = Object.assign(new Error(constants.ERROR_MESSAGE.COMMON_AUTH_ERROR_MESSAGE), { status: 401 });
                 return next(err);
             } else {
-                error.status = 500;
+                error.status = util.pageErrorStatus(error);
                 return next(error);
             }
         }
@@ -565,7 +565,7 @@ const loadDocsPage = async (req, res, next) => {
                 error: error.message,
                 stack: error.stack
             });
-            error.status = 500;
+            error.status = util.pageErrorStatus(error);
             return next(error);
         }
     }
@@ -613,7 +613,7 @@ const loadDocument = async (req, res, next) => {
                     const schemaAsIntrospectionJSON = await convertSDLToIntrospection(definitionResponse.swagger);
                     templateContent.graphqlSchemaAsIntrospectionJSON = schemaAsIntrospectionJSON ? JSON.stringify(schemaAsIntrospectionJSON) : null;
                     templateContent.graphqlSecurityScheme = '[]';
-                    templateContent.graphqlApiKeyHeader = config.security?.serviceApiKey?.headerName || 'apikey';
+                    templateContent.graphqlApiKeyHeader = 'apikey';
                     templateContent.apiMetadata = metaData;
                 } else {
                     templateContent.graphql = JSON.stringify(definitionResponse.swagger);
@@ -665,19 +665,23 @@ const loadDocument = async (req, res, next) => {
             templateContent.isGraphQLTryout = tryoutEnabled;
         }
         let apiMetadata = definitionResponse.metaData;
-        
-        const isMCPFromRegistry = apiMetadata?.type === constants.API_TYPE.MCP && !apiMetadata?.refId;
 
         //load API definition
         if (req.originalUrl.includes(constants.FILE_NAME.API_SPECIFICATION_PATH)) {
 
-            if (isMCPFromRegistry) {
-                const remotes = apiMetadata?.remotes || [];
-                const serverUrl = remotes.length > 0 ? remotes[0].url : '';
-                templateContent.swagger = JSON.stringify({ servers: [{ url: serverUrl }] });
-            } else if (definitionResponse.apiType === constants.API_TYPE.MCP) {
-                // CP-registered MCP: use server URL from endPoints
-                templateContent.swagger = definitionResponse.swagger;
+            if (definitionResponse.apiType === constants.API_TYPE.MCP) {
+                // The playground reads its server URL from servers[0].url. A
+                // registry-sourced MCP carries that endpoint in remotes[]; one
+                // registered through the control plane carries it in endPoints
+                // (getAPIDefinition already wraps it as {servers:[...]}).
+                // Keying purely on refId sent every MCP created directly in the
+                // portal — which has no refId *and* no remotes[] — down the
+                // remotes path, leaving the playground with a blank URL. Prefer
+                // remotes when present, otherwise fall back to endPoints.
+                const remoteUrl = (apiMetadata?.remotes || [])[0]?.url;
+                templateContent.swagger = remoteUrl
+                    ? JSON.stringify({ servers: [{ url: remoteUrl }] })
+                    : definitionResponse.swagger;
             } else if (definitionResponse.apiType !== constants.API_TYPE.WS && definitionResponse.apiType !== constants.API_TYPE.GRAPHQL && definitionResponse.apiType !== constants.API_TYPE.WEBSUB) {
                 let modifiedSwagger;
                 try {
@@ -734,7 +738,7 @@ const loadDocument = async (req, res, next) => {
                     const schemaAsIntrospectionJSON = await convertSDLToIntrospection(definitionResponse.graphql);
                     templateContent.graphqlSchemaAsIntrospectionJSON = schemaAsIntrospectionJSON ? JSON.stringify(schemaAsIntrospectionJSON) : null;
                     templateContent.graphqlSecurityScheme = '[]';
-                    templateContent.graphqlApiKeyHeader = config.security?.serviceApiKey?.headerName || 'apikey';
+                    templateContent.graphqlApiKeyHeader = 'apikey';
                 } else {
                     templateContent.graphql = definitionResponse.graphql ? JSON.stringify(definitionResponse.graphql) : '""';
                     templateContent.apiMetadataJSON = JSON.stringify(apiMetadata || {});
@@ -804,7 +808,7 @@ const loadDocument = async (req, res, next) => {
                 error: error.message,
                 stack: error.stack
             });
-            error.status = 500;
+            error.status = util.pageErrorStatus(error);
             return next(error);
         }
         res.send(html);
@@ -813,7 +817,7 @@ const loadDocument = async (req, res, next) => {
             const err = Object.assign(new Error(constants.ERROR_MESSAGE.COMMON_AUTH_ERROR_MESSAGE), { status: 401 });
             return next(err);
         } else {
-            error.status = 500;
+            error.status = util.pageErrorStatus(error);
             return next(error);
         }
     }
@@ -1124,6 +1128,26 @@ async function convertSDLToIntrospection(sdl) {
 }
 
 
+/**
+ * Markdown/agent-facing endpoints answer in text rather than the HTML error
+ * page, so they can't hand the error to the central handler. A URL naming a
+ * view or API that doesn't exist is still the caller's mistake, not a server
+ * fault — the DAOs raise those as CustomError(404), whose status sits on
+ * `statusCode`, so treating every failure as 500 told an agent to retry
+ * something that will never succeed.
+ *
+ * `mediaType` must match what the handler's success path sets. The failure can
+ * happen before that header is applied, and `res.send(string)` then defaults to
+ * text/html — so an agent asking for markdown got a markdown body labelled HTML.
+ */
+function sendMarkdownError(res, error, failureMessage, mediaType = 'text/markdown; charset=utf-8') {
+    res.setHeader('Content-Type', mediaType);
+    if (util.pageErrorStatus(error) === 404) {
+        return res.status(404).send('# Not Found\n\nThe requested resource does not exist.');
+    }
+    return res.status(500).send(`# Error\n\n${failureMessage}`);
+}
+
 const loadAPIContentMd = async (req, res) => {
     const { orgName, apiHandle, viewName } = req.params;
 
@@ -1247,7 +1271,7 @@ const loadAPIContentMd = async (req, res) => {
             error: error.message,
             stack: error.stack
         });
-        res.status(500).send('# Error\n\nFailed to load API details.');
+        sendMarkdownError(res, error, 'Failed to load API details.');
     }
 };
 
@@ -1324,7 +1348,7 @@ const loadLlmsTxt = async (req, res) => {
         res.send(md);
     } catch (error) {
         logger.error('Error generating llms.txt', { orgName, error: error.message, stack: error.stack });
-        res.status(500).send('# Error\n\nFailed to generate portal index.');
+        sendMarkdownError(res, error, 'Failed to generate portal index.', 'text/plain; charset=utf-8');
     }
 };
 
@@ -1349,7 +1373,7 @@ const previewLlmsTxt = async (req, res) => {
         res.send(md);
     } catch (error) {
         logger.error('Error previewing llms.txt', { orgName, error: error.message, stack: error.stack });
-        res.status(500).send('# Error\n\nFailed to generate preview.');
+        sendMarkdownError(res, error, 'Failed to generate preview.', 'text/plain; charset=utf-8');
     }
 };
 
@@ -1369,9 +1393,15 @@ const loadAPIsMd = async (req, res) => {
         const hiddenAPICount = metaDataList.length - agentVisibleAPIs.length;
 
         const nonMcpAPIs = agentVisibleAPIs.filter(api => api.type !== constants.API_TYPE.MCP);
+        // api.type holds the stored constant (e.g. "RestApi", "WebSubApi" — see
+        // constants.API_TYPE), not the enum key used below — map it back or every
+        // REST/WebSub API silently drops out of this catalog.
+        const typeConstantToEnum = Object.fromEntries(
+            Object.entries(constants.API_TYPE).map(([enumKey, storedValue]) => [storedValue, enumKey])
+        );
         const byType = { REST: [], GRAPHQL: [], WS: [], WEBSUB: [] };
         for (const api of nonMcpAPIs) {
-            const type = api.type;
+            const type = typeConstantToEnum[api.type];
             if (byType[type]) byType[type].push(api);
         }
         const baseUrl = '/' + orgName + constants.ROUTE.VIEWS_PATH + viewName;
@@ -1398,7 +1428,7 @@ const loadAPIsMd = async (req, res) => {
             error: error.message,
             stack: error.stack
         });
-        res.status(500).send('# Error\n\nFailed to load API list.');
+        sendMarkdownError(res, error, 'Failed to load API list.');
     }
 };
 
@@ -1439,7 +1469,7 @@ const loadMCPsMd = async (req, res) => {
             error: error.message,
             stack: error.stack
         });
-        res.status(500).send('# Error\n\nFailed to load MCP list.');
+        sendMarkdownError(res, error, 'Failed to load MCP list.');
     }
 };
 
@@ -1550,7 +1580,7 @@ const loadDocumentMd = async (req, res) => {
             error: error.message,
             stack: error.stack
         });
-        res.status(500).send('# Error\n\nFailed to load document.');
+        sendMarkdownError(res, error, 'Failed to load document.');
     }
 };
 
diff --git a/portals/api-portal/src/controllers/apiKeysOverviewController.js b/portals/api-portal/src/controllers/apiKeysOverviewController.js
index 41da4397a5..ebea5f14d9 100644
--- a/portals/api-portal/src/controllers/apiKeysOverviewController.js
+++ b/portals/api-portal/src/controllers/apiKeysOverviewController.js
@@ -16,7 +16,7 @@
  * under the License.
  */
  
-const { renderTemplateWithView, resolveActor } = require('../utils/util');
+const { renderTemplateWithView, resolveActor, pageErrorStatus } = require('../utils/util');
 const logger = require('../config/logger');
 const constants = require('../utils/constants');
 const orgDao = require('../dao/organizationDao');
@@ -88,7 +88,7 @@ const loadApiKeysOverview = async (req, res, next) => {
             stack: error.stack,
             orgName,
         });
-        error.status = 500;
+        error.status = pageErrorStatus(error);
         return next(error);
     }
 };
diff --git a/portals/api-portal/src/controllers/apiWorkflowsController.js b/portals/api-portal/src/controllers/apiWorkflowsController.js
index 45e75ee3e9..6c2d4eb8c0 100644
--- a/portals/api-portal/src/controllers/apiWorkflowsController.js
+++ b/portals/api-portal/src/controllers/apiWorkflowsController.js
@@ -137,7 +137,7 @@ const loadAPIWorkflows = async (req, res, next) => {
             orgName,
             viewName
         });
-        error.status = 500;
+        error.status = util.pageErrorStatus(error);
         return next(error);
     }
 };
@@ -218,7 +218,7 @@ const loadAPIWorkflowDetail = async (req, res, next) => {
             viewName,
             handle
         });
-        error.status = 500;
+        error.status = util.pageErrorStatus(error);
         return next(error);
     }
 };
diff --git a/portals/api-portal/src/controllers/applicationsContentController.js b/portals/api-portal/src/controllers/applicationsContentController.js
index 4e35dc7fd3..c3d5e7d981 100644
--- a/portals/api-portal/src/controllers/applicationsContentController.js
+++ b/portals/api-portal/src/controllers/applicationsContentController.js
@@ -16,7 +16,7 @@
  * under the License.
  */
  
-const { renderTemplate, renderGivenTemplate, loadLayoutFromAPI, resolveActor } = require('../utils/util');
+const { renderTemplate, renderGivenTemplate, loadLayoutFromAPI, resolveActor, pageErrorStatus } = require('../utils/util');
 const { config } = require('../config/configLoader');
 const logger = require('../config/logger');
 const constants = require('../utils/constants');
@@ -230,7 +230,7 @@ const loadApplications = async (req, res, next) => {
             error: error.message,
             stack: error.stack
         });
-        error.status = 500;
+        error.status = pageErrorStatus(error);
         return next(error);
     }
     res.send(html);
diff --git a/portals/api-portal/src/controllers/customContentController.js b/portals/api-portal/src/controllers/customContentController.js
index faae42d2f1..1f69f15cde 100644
--- a/portals/api-portal/src/controllers/customContentController.js
+++ b/portals/api-portal/src/controllers/customContentController.js
@@ -16,7 +16,7 @@
  * under the License.
  */
  
-const { renderTemplate, renderTemplateFromAPI, loadMarkdown, filePrefix } = require('../utils/util');
+const { renderTemplate, renderTemplateFromAPI, loadMarkdown, filePrefix, pageErrorStatus } = require('../utils/util');
 const { config } = require('../config/configLoader');
 const markdown = require('marked');
 const fs = require('fs');
@@ -74,11 +74,16 @@ const loadCustomContent = async (req, res, next) => {
             // Check if the file exists before attempting to render
             const resolvedPagePath = path.join(process.cwd(), filePrefix + filePath + '/page.hbs');
             if (!fs.existsSync(resolvedPagePath)) {
-                // If it's a manage-keys route that doesn't exist, return 404 or redirect
-                if (filePath.includes('manage-keys')) {
-                    throw new Error(`Manage keys page not found. This route should be handled by the application controller.`);
-                }
-                throw new Error(`Content page not found at ${resolvedPagePath}`);
+                // Both branches mean "this page does not exist", so they carry a 404.
+                // A bare Error has no status, and pageErrorStatus() below falls back to
+                // 500 — which rendered a server-error page for what is simply a bad URL.
+                const notFound = filePath.includes('manage-keys')
+                    // A manage-keys route that got here was not claimed by the
+                    // application controller, so there is nothing to render.
+                    ? new Error('Manage keys page not found. This route should be handled by the application controller.')
+                    : new Error(`Content page not found at ${resolvedPagePath}`);
+                notFound.status = 404;
+                throw notFound;
             }
             const orgDetails = await orgDao.get(orgName);
             const orgId = orgDetails.uuid;
@@ -102,7 +107,7 @@ const loadCustomContent = async (req, res, next) => {
                 stack: error.stack,
                 filePath: req.params.filePath,
             });
-            error.status = 500;
+            error.status = pageErrorStatus(error);
             return next(error);
         }
     }
diff --git a/portals/api-portal/src/controllers/orgContentController.js b/portals/api-portal/src/controllers/orgContentController.js
index 5187c77160..a37283e9c0 100644
--- a/portals/api-portal/src/controllers/orgContentController.js
+++ b/portals/api-portal/src/controllers/orgContentController.js
@@ -17,7 +17,7 @@
  */
 /* eslint-disable no-undef */
 const logger = require('../config/logger');
-const { renderTemplate, renderTemplateFromAPI } = require('../utils/util');
+const { renderTemplate, renderTemplateFromAPI, pageErrorStatus } = require('../utils/util');
 const { config } = require('../config/configLoader');
 const constants = require('../utils/constants');
 const orgDao = require('../dao/organizationDao');
@@ -31,6 +31,10 @@ const loadOrganizationContent = async (req, res, next) => {
     } else {
         html = await loadOrgContentFromAPI(req, res, next);
     }
+    // loadOrgContentFromAPI returns undefined once it has handed the error to
+    // next() — the error handler has already written the response by then, so
+    // sending again would throw ERR_HTTP_HEADERS_SENT over the real error.
+    if (html === undefined || res.headersSent) return;
     res.send(html);
 }
 const loadOrgContentFromFile = async (req, res) => {
@@ -72,7 +76,7 @@ const loadOrgContentFromAPI = async (req, res, next) => {
             error: error.message,
             stack: error.stack
         });
-        error.status = 500;
+        error.status = pageErrorStatus(error);
         return next(error);
     }
     return html;
diff --git a/portals/api-portal/src/controllers/subscriptionsContentController.js b/portals/api-portal/src/controllers/subscriptionsContentController.js
index 0426f8e885..5cd3e56ed7 100644
--- a/portals/api-portal/src/controllers/subscriptionsContentController.js
+++ b/portals/api-portal/src/controllers/subscriptionsContentController.js
@@ -16,7 +16,7 @@
  * under the License.
  */
  
-const { renderTemplateWithView, resolveActor } = require('../utils/util');
+const { renderTemplateWithView, resolveActor, pageErrorStatus } = require('../utils/util');
 const logger = require('../config/logger');
 const constants = require('../utils/constants');
 const orgDao = require('../dao/organizationDao');
@@ -79,7 +79,7 @@ const loadSubscriptions = async (req, res, next) => {
             stack: error.stack,
             orgName
         });
-        error.status = 500;
+        error.status = pageErrorStatus(error);
         return next(error);
     }
 };
diff --git a/portals/api-portal/src/dao/organizationDao.js b/portals/api-portal/src/dao/organizationDao.js
index 3bdce9a63f..b3692830ce 100644
--- a/portals/api-portal/src/dao/organizationDao.js
+++ b/portals/api-portal/src/dao/organizationDao.js
@@ -138,18 +138,19 @@ const update = async (orgData, t) => {
     const orgHandle = orgData.handle ? orgData.handle.toLowerCase() : existing.handle;
     const updatedAt = new Date();
 
+    // cp_ref_id is written unconditionally, exactly like idp_ref_id: both are
+    // plain optional reference fields with no derived default, so a blank one
+    // clears the stored value rather than silently keeping the old one.
     const setClauses = [
         'display_name = ?', 'business_owner = ?', 'business_owner_contact = ?',
-        'business_owner_email = ?', 'handle = ?', 'idp_ref_id = ?', 'updated_by = ?', 'updated_at = ?',
+        'business_owner_email = ?', 'handle = ?', 'idp_ref_id = ?', 'cp_ref_id = ?',
+        'updated_by = ?', 'updated_at = ?',
     ];
     const params = [
         orgData.displayName, orgData.businessOwner, orgData.businessOwnerContact,
-        orgData.businessOwnerEmail, orgHandle, orgData.idpRefId, orgData.updatedBy, updatedAt,
+        orgData.businessOwnerEmail, orgHandle, orgData.idpRefId, orgData.cpRefId,
+        orgData.updatedBy, updatedAt,
     ];
-    if (orgData.cpRefId !== undefined) {
-        setClauses.push('cp_ref_id = ?');
-        params.push(orgData.cpRefId);
-    }
     if (orgData.configuration !== undefined) {
         setClauses.push('configuration = ?');
         params.push(orgData.configuration);
diff --git a/portals/api-portal/src/defaultContent/images/api-portal-logo-white.png b/portals/api-portal/src/defaultContent/images/api-portal-logo-white.png
new file mode 100644
index 0000000000..9a99bf6184
Binary files /dev/null and b/portals/api-portal/src/defaultContent/images/api-portal-logo-white.png differ
diff --git a/portals/api-portal/src/defaultContent/images/api-portal-logo-white.svg b/portals/api-portal/src/defaultContent/images/api-portal-logo-white.svg
new file mode 100644
index 0000000000..4ba5bec9a4
--- /dev/null
+++ b/portals/api-portal/src/defaultContent/images/api-portal-logo-white.svg
@@ -0,0 +1,5 @@
+<svg width="872" height="97" viewBox="0 0 872 97" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M45.6502 67.8639C45.6058 67.8639 45.5615 67.8639 45.5171 67.8599C44.5553 67.8014 43.7366 67.138 43.4825 66.2084L36.2133 39.5511L32.4909 51.9845C32.2066 52.9342 31.3315 53.5876 30.3394 53.5876H16.3957C15.1556 53.5876 14.1494 52.5814 14.1494 51.3412C14.1494 50.1011 15.1556 49.0949 16.3957 49.0949H28.6678L34.1646 30.7393C34.4509 29.7875 35.324 29.1362 36.3161 29.1362C36.3242 29.1362 36.3343 29.1362 36.3443 29.1362C37.3465 29.1483 38.2196 29.8238 38.4838 30.7917L46.0696 58.6065L49.3564 50.4964C49.6992 49.6474 50.5239 49.0929 51.4394 49.0929H62.6105C63.8506 49.0929 64.8568 50.0991 64.8568 51.3392C64.8568 52.5793 63.8506 53.5855 62.6105 53.5855H52.9517L47.7352 66.4585C47.3904 67.3094 46.5637 67.8619 45.6542 67.8619L45.6502 67.8639Z" fill="white"/>
+<path d="M39.5 88C17.7205 88 0 70.2816 0 48.5C0 26.7184 17.7184 9 39.5 9C61.2816 9 79 26.7205 79 48.5C79 70.2795 61.2795 88 39.5 88ZM39.5 13.4926C20.1987 13.4926 4.49464 29.1966 4.49464 48.5C4.49464 67.8034 20.1987 83.5054 39.5 83.5054C58.8013 83.5054 74.5054 67.8013 74.5054 48.5C74.5054 29.1987 58.8013 13.4926 39.5 13.4926Z" fill="white"/>
+<path d="M109.21 78H97.9602L118.443 19.8182H131.455L151.966 78H140.716L125.176 31.75H124.722L109.21 78ZM109.58 55.1875H140.261V63.6534H109.58V55.1875ZM156.429 78V19.8182H178.247C182.717 19.8182 186.467 20.6515 189.497 22.3182C192.547 23.9848 194.848 26.2765 196.401 29.1932C197.973 32.0909 198.759 35.3864 198.759 39.0795C198.759 42.8106 197.973 46.125 196.401 49.0227C194.829 51.9205 192.509 54.2027 189.441 55.8693C186.372 57.517 182.594 58.3409 178.105 58.3409H163.645V49.6761H176.685C179.299 49.6761 181.439 49.2216 183.105 48.3125C184.772 47.4034 186.003 46.1534 186.799 44.5625C187.613 42.9716 188.02 41.1439 188.02 39.0795C188.02 37.0152 187.613 35.197 186.799 33.625C186.003 32.053 184.763 30.8314 183.077 29.9602C181.41 29.0701 179.261 28.625 176.628 28.625H166.969V78H156.429ZM215.253 19.8182V78H204.714V19.8182H215.253ZM240.111 78V19.8182H261.929C266.398 19.8182 270.148 20.6515 273.179 22.3182C276.228 23.9848 278.529 26.2765 280.082 29.1932C281.654 32.0909 282.44 35.3864 282.44 39.0795C282.44 42.8106 281.654 46.125 280.082 49.0227C278.51 51.9205 276.19 54.2027 273.122 55.8693C270.054 57.517 266.275 58.3409 261.787 58.3409H247.326V49.6761H260.366C262.98 49.6761 265.12 49.2216 266.787 48.3125C268.453 47.4034 269.684 46.1534 270.48 44.5625C271.294 42.9716 271.701 41.1439 271.701 39.0795C271.701 37.0152 271.294 35.197 270.48 33.625C269.684 32.053 268.444 30.8314 266.758 29.9602C265.092 29.0701 262.942 28.625 260.309 28.625H250.65V78H240.111ZM306.349 78.8523C302.088 78.8523 298.395 77.9148 295.27 76.0398C292.145 74.1648 289.721 71.5417 287.997 68.1705C286.293 64.7992 285.44 60.8598 285.44 56.3523C285.44 51.8447 286.293 47.8958 287.997 44.5057C289.721 41.1155 292.145 38.483 295.27 36.608C298.395 34.733 302.088 33.7955 306.349 33.7955C310.611 33.7955 314.304 34.733 317.429 36.608C320.554 38.483 322.969 41.1155 324.673 44.5057C326.397 47.8958 327.259 51.8447 327.259 56.3523C327.259 60.8598 326.397 64.7992 324.673 68.1705C322.969 71.5417 320.554 74.1648 317.429 76.0398C314.304 77.9148 310.611 78.8523 306.349 78.8523ZM306.406 70.6136C308.717 70.6136 310.649 69.9792 312.202 68.7102C313.755 67.4223 314.91 65.6989 315.668 63.5398C316.444 61.3807 316.832 58.9754 316.832 56.3239C316.832 53.6534 316.444 51.2386 315.668 49.0795C314.91 46.9015 313.755 45.1686 312.202 43.8807C310.649 42.5928 308.717 41.9489 306.406 41.9489C304.039 41.9489 302.069 42.5928 300.497 43.8807C298.944 45.1686 297.779 46.9015 297.003 49.0795C296.245 51.2386 295.866 53.6534 295.866 56.3239C295.866 58.9754 296.245 61.3807 297.003 63.5398C297.779 65.6989 298.944 67.4223 300.497 68.7102C302.069 69.9792 304.039 70.6136 306.406 70.6136ZM332.787 78V34.3636H342.759V41.6364H343.213C344.009 39.1174 345.372 37.1761 347.304 35.8125C349.255 34.4299 351.48 33.7386 353.98 33.7386C354.549 33.7386 355.183 33.767 355.884 33.8239C356.604 33.8617 357.2 33.928 357.674 34.0227V43.483C357.238 43.3314 356.547 43.1989 355.6 43.0852C354.672 42.9527 353.772 42.8864 352.901 42.8864C351.026 42.8864 349.34 43.2936 347.844 44.108C346.367 44.9034 345.202 46.0114 344.35 47.4318C343.497 48.8523 343.071 50.4905 343.071 52.3466V78H332.787ZM385.439 34.3636V42.3182H360.354V34.3636H385.439ZM366.547 23.9091H376.832V64.875C376.832 66.2576 377.04 67.3182 377.457 68.0568C377.892 68.7765 378.46 69.2689 379.161 69.5341C379.862 69.7992 380.638 69.9318 381.491 69.9318C382.135 69.9318 382.722 69.8845 383.252 69.7898C383.801 69.6951 384.218 69.6098 384.502 69.5341L386.235 77.5739C385.686 77.7633 384.9 77.9716 383.877 78.1989C382.873 78.4261 381.642 78.5587 380.184 78.5966C377.608 78.6723 375.288 78.2841 373.224 77.4318C371.159 76.5606 369.521 75.2159 368.309 73.3977C367.116 71.5795 366.529 69.3068 366.547 66.5795V23.9091ZM403.397 78.8807C400.632 78.8807 398.141 78.3883 395.926 77.4034C393.729 76.3996 391.986 74.9223 390.698 72.9716C389.429 71.0208 388.795 68.6155 388.795 65.7557C388.795 63.2936 389.249 61.2576 390.159 59.6477C391.068 58.0379 392.308 56.75 393.88 55.7841C395.452 54.8182 397.223 54.089 399.193 53.5966C401.181 53.0852 403.236 52.7159 405.357 52.4886C407.914 52.2235 409.988 51.9867 411.579 51.7784C413.17 51.5511 414.325 51.2102 415.045 50.7557C415.784 50.2822 416.153 49.553 416.153 48.5682V48.3977C416.153 46.2576 415.518 44.6004 414.249 43.4261C412.98 42.2519 411.153 41.6648 408.766 41.6648C406.248 41.6648 404.249 42.214 402.772 43.3125C401.314 44.411 400.329 45.7083 399.818 47.2045L390.215 45.8409C390.973 43.1894 392.223 40.9735 393.965 39.1932C395.708 37.3939 397.838 36.0492 400.357 35.1591C402.876 34.25 405.66 33.7955 408.71 33.7955C410.812 33.7955 412.905 34.0417 414.988 34.5341C417.071 35.0265 418.975 35.8409 420.698 36.9773C422.422 38.0947 423.804 39.6193 424.846 41.5511C425.907 43.483 426.437 45.8977 426.437 48.7955V78H416.551V72.0057H416.21C415.585 73.2178 414.704 74.3542 413.568 75.4148C412.45 76.4564 411.039 77.2992 409.335 77.9432C407.649 78.5682 405.67 78.8807 403.397 78.8807ZM406.068 71.3239C408.132 71.3239 409.922 70.9167 411.437 70.1023C412.952 69.2689 414.117 68.1705 414.931 66.8068C415.765 65.4432 416.181 63.9564 416.181 62.3466V57.2045C415.859 57.4697 415.31 57.7159 414.534 57.9432C413.776 58.1705 412.924 58.3693 411.977 58.5398C411.03 58.7102 410.092 58.8617 409.164 58.9943C408.236 59.1269 407.431 59.2405 406.749 59.3352C405.215 59.5436 403.842 59.8845 402.63 60.358C401.418 60.8314 400.462 61.4943 399.761 62.3466C399.06 63.1799 398.71 64.2595 398.71 65.5852C398.71 67.4792 399.401 68.9091 400.784 69.875C402.166 70.8409 403.927 71.3239 406.068 71.3239ZM443.862 19.8182V78H433.578V19.8182H443.862ZM485.267 78.8523C481.29 78.8523 477.871 78.1326 475.012 76.6932C472.152 75.2538 469.945 73.3125 468.392 70.8693C466.858 68.4072 466.091 65.6326 466.091 62.5455C466.091 60.2159 466.565 58.1515 467.512 56.3523C468.478 54.553 469.803 52.8864 471.489 51.3523C473.193 49.8182 475.163 48.2936 477.398 46.7784L487.711 39.7614C489.226 38.7765 490.371 37.7348 491.148 36.6364C491.943 35.5379 492.341 34.25 492.341 32.7727C492.341 31.5227 491.811 30.339 490.75 29.2216C489.709 28.1042 488.269 27.5455 486.432 27.5455C485.201 27.5455 484.112 27.839 483.165 28.4261C482.237 28.9943 481.508 29.7424 480.978 30.6705C480.466 31.5985 480.211 32.5833 480.211 33.625C480.211 34.8939 480.561 36.1818 481.262 37.4886C481.981 38.7955 482.909 40.1496 484.046 41.5511C485.201 42.9527 486.432 44.4394 487.739 46.0114L515.04 78H503.904L481.233 52.0341C479.548 50.0644 477.919 48.1231 476.347 46.2102C474.794 44.2973 473.515 42.3087 472.512 40.2443C471.527 38.161 471.034 35.9072 471.034 33.483C471.034 30.7367 471.669 28.2841 472.938 26.125C474.207 23.947 475.978 22.233 478.25 20.983C480.542 19.733 483.222 19.108 486.29 19.108C489.358 19.108 491.991 19.714 494.188 20.9261C496.385 22.1383 498.08 23.7481 499.273 25.7557C500.466 27.7633 501.063 29.9508 501.063 32.3182C501.063 35.0644 500.381 37.5265 499.017 39.7045C497.654 41.8636 495.76 43.8239 493.336 45.5852L481.574 54.1932C479.642 55.5947 478.26 57.0152 477.426 58.4545C476.593 59.875 476.176 61.0871 476.176 62.0909C476.176 63.625 476.565 65.017 477.341 66.267C478.118 67.517 479.207 68.5208 480.608 69.2784C482.029 70.017 483.686 70.3864 485.58 70.3864C487.663 70.3864 489.718 69.9223 491.745 68.9943C493.771 68.0473 495.618 66.7027 497.284 64.9602C498.951 63.2178 500.277 61.1345 501.262 58.7102C502.246 56.267 502.739 53.5587 502.739 50.5852H511.574C511.574 54.2595 511.167 57.4602 510.353 60.1875C509.538 62.8958 508.487 65.1875 507.199 67.0625C505.911 68.9186 504.548 70.4053 503.108 71.5227C502.654 71.8447 502.218 72.1667 501.801 72.4886C501.385 72.8106 500.949 73.1326 500.495 73.4545C498.449 75.3106 496.053 76.6742 493.307 77.5455C490.58 78.4167 487.9 78.8523 485.267 78.8523ZM534.826 19.8182H547.724L564.997 61.9773H565.678L582.951 19.8182H595.849V78H585.735V38.0284H585.195L569.116 77.8295H561.559L545.48 37.9432H544.94V78H534.826V19.8182ZM653.927 39.4489H643.302C642.999 37.7064 642.441 36.1629 641.626 34.8182C640.812 33.4545 639.798 32.2992 638.586 31.3523C637.374 30.4053 635.992 29.6951 634.439 29.2216C632.905 28.7292 631.247 28.483 629.467 28.483C626.304 28.483 623.501 29.2784 621.058 30.8693C618.615 32.4413 616.702 34.7519 615.319 37.8011C613.937 40.8314 613.245 44.5341 613.245 48.9091C613.245 53.3598 613.937 57.1098 615.319 60.1591C616.721 63.1894 618.634 65.4811 621.058 67.0341C623.501 68.5682 626.295 69.3352 629.439 69.3352C631.181 69.3352 632.81 69.108 634.325 68.6534C635.859 68.1799 637.232 67.4886 638.444 66.5795C639.675 65.6705 640.708 64.553 641.541 63.2273C642.393 61.9015 642.98 60.3864 643.302 58.6818L653.927 58.7386C653.53 61.5038 652.668 64.0985 651.342 66.5227C650.035 68.947 648.321 71.0871 646.2 72.9432C644.079 74.7803 641.598 76.2197 638.757 77.2614C635.916 78.2841 632.763 78.7955 629.297 78.7955C624.183 78.7955 619.619 77.6117 615.603 75.2443C611.588 72.8769 608.425 69.4583 606.115 64.9886C603.804 60.5189 602.649 55.1591 602.649 48.9091C602.649 42.6402 603.814 37.2803 606.143 32.8295C608.473 28.3598 611.645 24.9413 615.66 22.5739C619.675 20.2064 624.221 19.0227 629.297 19.0227C632.535 19.0227 635.547 19.4773 638.331 20.3864C641.115 21.2955 643.596 22.6307 645.774 24.392C647.952 26.1345 649.742 28.2746 651.143 30.8125C652.564 33.3314 653.492 36.2102 653.927 39.4489ZM660.379 78V19.8182H682.197C686.667 19.8182 690.417 20.6515 693.447 22.3182C696.497 23.9848 698.798 26.2765 700.351 29.1932C701.923 32.0909 702.709 35.3864 702.709 39.0795C702.709 42.8106 701.923 46.125 700.351 49.0227C698.779 51.9205 696.459 54.2027 693.391 55.8693C690.322 57.517 686.544 58.3409 682.055 58.3409H667.595V49.6761H680.635C683.249 49.6761 685.389 49.2216 687.055 48.3125C688.722 47.4034 689.953 46.1534 690.749 44.5625C691.563 42.9716 691.97 41.1439 691.97 39.0795C691.97 37.0152 691.563 35.197 690.749 33.625C689.953 32.053 688.713 30.8314 687.027 29.9602C685.36 29.0701 683.211 28.625 680.578 28.625H670.919V78H660.379ZM725.307 78V19.8182H735.847V44.4489H762.807V19.8182H773.376V78H762.807V53.2841H735.847V78H725.307ZM808.997 59.6477V34.3636H819.281V78H809.309V70.2443H808.855C807.87 72.6875 806.25 74.6856 803.997 76.2386C801.762 77.7917 799.006 78.5682 795.73 78.5682C792.87 78.5682 790.341 77.9337 788.144 76.6648C785.966 75.3769 784.262 73.5114 783.031 71.0682C781.8 68.6061 781.184 65.6326 781.184 62.1477V34.3636H791.468V60.5568C791.468 63.322 792.226 65.5189 793.741 67.1477C795.256 68.7765 797.245 69.5909 799.707 69.5909C801.222 69.5909 802.69 69.2216 804.11 68.483C805.531 67.7443 806.695 66.6458 807.605 65.1875C808.533 63.7102 808.997 61.8636 808.997 59.6477ZM827.111 78V19.8182H837.395V41.5795H837.821C838.351 40.5189 839.099 39.392 840.065 38.1989C841.031 36.9867 842.338 35.9545 843.986 35.1023C845.633 34.2311 847.736 33.7955 850.292 33.7955C853.664 33.7955 856.703 34.6572 859.412 36.3807C862.139 38.0852 864.298 40.6136 865.889 43.9659C867.499 47.2992 868.304 51.3902 868.304 56.2386C868.304 61.0303 867.518 65.1023 865.946 68.4545C864.374 71.8068 862.234 74.3636 859.525 76.125C856.817 77.8864 853.749 78.767 850.321 78.767C847.821 78.767 845.747 78.3504 844.099 77.517C842.451 76.6837 841.126 75.6799 840.122 74.5057C839.137 73.3125 838.37 72.1856 837.821 71.125H837.224V78H827.111ZM837.196 56.1818C837.196 59.0038 837.593 61.4754 838.389 63.5966C839.203 65.7178 840.368 67.375 841.883 68.5682C843.417 69.7424 845.273 70.3295 847.451 70.3295C849.724 70.3295 851.628 69.7235 853.162 68.5114C854.696 67.2803 855.851 65.6042 856.628 63.483C857.423 61.3428 857.821 58.9091 857.821 56.1818C857.821 53.4735 857.432 51.0682 856.656 48.9659C855.879 46.8636 854.724 45.2159 853.19 44.0227C851.656 42.8295 849.743 42.233 847.451 42.233C845.254 42.233 843.389 42.8106 841.855 43.9659C840.321 45.1212 839.156 46.7405 838.361 48.8239C837.584 50.9072 837.196 53.3598 837.196 56.1818Z" fill="white"/>
+</svg>
diff --git a/portals/api-portal/src/defaultContent/pages/apis/partials/apis-md.hbs b/portals/api-portal/src/defaultContent/pages/apis/partials/apis-md.hbs
index 019426ead1..ead1ef2850 100644
--- a/portals/api-portal/src/defaultContent/pages/apis/partials/apis-md.hbs
+++ b/portals/api-portal/src/defaultContent/pages/apis/partials/apis-md.hbs
@@ -6,7 +6,7 @@ Explore our extensive API catalog and discover how to integrate them seamlessly
 # APIs
 
 {{#restAPIs}}
-- [{{name}} v{{version}}]({{../baseUrl}}/api/{{id}}.md){{#if description}} - {{description}}{{/if}}
+- [{{name}} {{version}}]({{../baseUrl}}/api/{{id}}.md){{#if description}} - {{description}}{{/if}}
 {{/restAPIs}}
 {{/if}}
 {{#if graphqlAPIs}}
@@ -14,7 +14,7 @@ Explore our extensive API catalog and discover how to integrate them seamlessly
 # GraphQL APIs
 
 {{#graphqlAPIs}}
-- [{{name}} v{{version}}]({{../baseUrl}}/api/{{id}}.md){{#if description}} - {{description}}{{/if}}
+- [{{name}} {{version}}]({{../baseUrl}}/api/{{id}}.md){{#if description}} - {{description}}{{/if}}
 {{/graphqlAPIs}}
 {{/if}}
 {{#if wsAPIs}}
@@ -22,7 +22,7 @@ Explore our extensive API catalog and discover how to integrate them seamlessly
 # Async / WebSocket APIs
 
 {{#wsAPIs}}
-- [{{name}} v{{version}}]({{../baseUrl}}/api/{{id}}.md){{#if description}} - {{description}}{{/if}}
+- [{{name}} {{version}}]({{../baseUrl}}/api/{{id}}.md){{#if description}} - {{description}}{{/if}}
 {{/wsAPIs}}
 {{/if}}
 {{#if websubAPIs}}
@@ -30,6 +30,6 @@ Explore our extensive API catalog and discover how to integrate them seamlessly
 # WebSub APIs
 
 {{#websubAPIs}}
-- [{{name}} v{{version}}]({{../baseUrl}}/api/{{id}}.md){{#if description}} - {{description}}{{/if}}
+- [{{name}} {{version}}]({{../baseUrl}}/api/{{id}}.md){{#if description}} - {{description}}{{/if}}
 {{/websubAPIs}}
 {{/if}}
diff --git a/portals/api-portal/src/defaultContent/pages/docs/page.hbs b/portals/api-portal/src/defaultContent/pages/docs/page.hbs
index 00475b3b49..2a31cb9654 100644
--- a/portals/api-portal/src/defaultContent/pages/docs/page.hbs
+++ b/portals/api-portal/src/defaultContent/pages/docs/page.hbs
@@ -19,7 +19,7 @@
  <div class="page-container">
 <nav class="dp-breadcrumb">
   {{#if (eq apiType "Mcp")}}
-    <a class="dp-breadcrumb-item" href="{{baseUrl}}/mcp">MCP Servers</a>
+    <a class="dp-breadcrumb-item" href="{{baseUrl}}/mcps">MCP Servers</a>
   {{else}}
     <a class="dp-breadcrumb-item" href="{{baseUrl}}/apis">APIs</a>
   {{/if}}
diff --git a/portals/api-portal/src/defaultContent/pages/mcp-landing/page.hbs b/portals/api-portal/src/defaultContent/pages/mcp-landing/page.hbs
index 3f88edb42d..69d40a5ea0 100644
--- a/portals/api-portal/src/defaultContent/pages/mcp-landing/page.hbs
+++ b/portals/api-portal/src/defaultContent/pages/mcp-landing/page.hbs
@@ -29,7 +29,7 @@
 {{/pageScripts}}
 <div style="padding: 1rem 1.5rem 0;">
   <nav class="dp-breadcrumb">
-    <a class="dp-breadcrumb-item" href="{{baseUrl}}/mcp">MCP Servers</a>
+    <a class="dp-breadcrumb-item" href="{{baseUrl}}/mcps">MCP Servers</a>
     <i class="bi bi-chevron-right dp-breadcrumb-sep"></i>
     <span class="dp-breadcrumb-current">{{or apiMetadata.title apiMetadata.name}}</span>
   </nav>
diff --git a/portals/api-portal/src/defaultContent/pages/mcps/partials/mcps-md.hbs b/portals/api-portal/src/defaultContent/pages/mcps/partials/mcps-md.hbs
index a9d2da497b..be2cc1a239 100644
--- a/portals/api-portal/src/defaultContent/pages/mcps/partials/mcps-md.hbs
+++ b/portals/api-portal/src/defaultContent/pages/mcps/partials/mcps-md.hbs
@@ -6,6 +6,6 @@ Explore our MCP server catalog and connect AI agents to powerful tools and data
 # MCP Servers
 
 {{#mcpAPIs}}
-- [{{name}} v{{version}}]({{../baseUrl}}/mcp/{{id}}.md){{#if description}} - {{description}}{{/if}}
+- [{{name}} {{version}}]({{../baseUrl}}/mcp/{{id}}.md){{#if description}} - {{description}}{{/if}}
 {{/mcpAPIs}}
 {{/if}}
diff --git a/portals/api-portal/src/middlewares/authMiddleware.js b/portals/api-portal/src/middlewares/authMiddleware.js
index 8a85d6285c..f09b93afa4 100644
--- a/portals/api-portal/src/middlewares/authMiddleware.js
+++ b/portals/api-portal/src/middlewares/authMiddleware.js
@@ -243,14 +243,14 @@ async function resolveScopedOrg(req, identifier, source) {
 }
 
 /**
- * Sets req.orgId for credentials that carry no organization of their own (service
- * API key, mTLS) — they are authenticated as this portal's operator, so the only
- * organization they can be acting on is the one this instance serves.
+ * Sets req.orgId for credentials that carry no organization of their own (mTLS) —
+ * they are authenticated as this portal's operator, so the only organization they
+ * can be acting on is the one this instance serves.
  *
  * An `organization` header is no longer what selects the organization; it is only
- * checked for disagreement. Honouring it would let a single API key address every
- * tenant in the shared database. Rejecting a mismatch rather than ignoring it keeps
- * a caller from believing it wrote to the organization it named.
+ * checked for disagreement. Honouring it would let a single credential address
+ * every tenant in the shared database. Rejecting a mismatch rather than ignoring
+ * it keeps a caller from believing it wrote to the organization it named.
  *
  * @returns {Promise<Error|null>} null on success, or an Error with .status
  */
@@ -315,7 +315,7 @@ async function authResolver(req, res, next) {
         // 2. Session fast-path: browser login via IDP.
         //
         // In "scope" mode the per-operation check is bypassed (preauthorized, same as the
-        // API key and mTLS paths): the IDP mints whatever scopes its client is registered
+        // mTLS path): the IDP mints whatever scopes its client is registered
         // for, which would mean listing all dp:* scopes in the OIDC scope config, so the
         // authorization that actually applies to these sessions is ensureAuthenticated's
         // page role check.
@@ -397,21 +397,9 @@ async function authResolver(req, res, next) {
             return next();
         }
 
-        // 4. API key — org resolved from the `organization` request header
-        if (config.security?.serviceApiKey?.enabled) {
-            const keyType = config.security.serviceApiKey.headerName;
-            if (keyType && config.security?.serviceApiKey?.value) {
-                const apiKey = req.headers[keyType.toLowerCase()];
-                if (apiKey && apiKey === config.security?.serviceApiKey?.value) {
-                    const orgErr = await resolvePortalOrg(req);
-                    if (orgErr) return next(orgErr);
-                    req.auth = { mode: 'apikey', preauthorized: true, scopes: [] };
-                    return next();
-                }
-            }
-        }
-
-        // 5. mTLS — org resolved from the `organization` request header
+        // 4. mTLS — the organization is this instance's own; resolvePortalOrg only
+        // VALIDATES an `organization` header if one is present (403 on anything but
+        // the pinned org), it does not let the header choose the organization.
         if (typeof req.socket?.getPeerCertificate === 'function') {
             const cert = req.socket.getPeerCertificate(true);
             if (cert && Object.keys(cert).length > 0 && req.client?.authorized) {
@@ -425,7 +413,7 @@ async function authResolver(req, res, next) {
             }
         }
 
-        // 6. No usable credential — pass through as anonymous so the OpenAPI
+        // 5. No usable credential — pass through as anonymous so the OpenAPI
         // validator can enforce security on a per-operation basis. Operations
         // with `security: []` (public endpoints) will proceed; operations that
         // declare a security scheme will have their handler invoked by the
@@ -476,16 +464,21 @@ async function OAuth2Security(req /* , requiredScopes, schema */) {
 }
 
 /**
- * API key security handler. Accepts the request if authResolver already
- * authenticated it via API key (or any preauthorized non-OAuth mode, to
- * mirror legacy behaviour where API key endpoints also accepted basic/mTLS).
- */
-/*
- * TODO: once the API key support introduces with scope support, change the method
- * to check for scopes as well, and rename it to ApiKeySecurity for clarity.
+ * Handler for the spec's `apiKeyAuth` security scheme. No operation currently
+ * declares that scheme, so the validator never invokes this — it stays wired up
+ * so adding `security: [apiKeyAuth]` to an operation doesn't fail at startup.
+ *
+ * Accepts a request only when `req.auth?.preauthorized` is true. That covers mTLS
+ * and, because authResolver sets `preauthorized: !isRoleMode()`, OAuth2 sessions in
+ * scope mode too. It does NOT cover a role-mode session, where that flag is false
+ * precisely so the per-operation scope check still runs.
+ *
+ * The portal's own static shared-secret header auth (`service_api_key`) was
+ * removed; this is not a revival of it. Any future API key scheme needs its own
+ * credential store and a real scope check here, not a config constant.
  */
 async function apiKeyAuth(req /* , scopes, schema */) {
-    if (req.auth?.mode === 'apikey' || req.auth?.preauthorized) return true;
+    if (req.auth?.preauthorized) return true;
     const err = new Error('Authentication required');
     err.status = 401;
     throw err;
diff --git a/portals/api-portal/src/middlewares/csrfProtection.js b/portals/api-portal/src/middlewares/csrfProtection.js
index 5b50ee5798..e9e8cda993 100644
--- a/portals/api-portal/src/middlewares/csrfProtection.js
+++ b/portals/api-portal/src/middlewares/csrfProtection.js
@@ -17,7 +17,6 @@
  */
  
 const crypto = require('crypto');
-const { config } = require('../config/configLoader');
 
 const CSRF_HMAC_LABEL = 'api-portal-api-keys-csrf';
 
@@ -48,15 +47,6 @@ function hasBearerAuthorization(req) {
     return typeof a === 'string' && a.length > 6 && a.toLowerCase().startsWith('bearer ');
 }
 
-function hasConfiguredApiKey(req) {
-    if (!config.security?.serviceApiKey?.enabled || !config.security.serviceApiKey.headerName || !config.security.serviceApiKey.value) {
-        return false;
-    }
-    const keyType = config.security.serviceApiKey.headerName;
-    const sentKey = req.headers[keyType.toLowerCase()] || req.headers[keyType];
-    return sentKey === config.security.serviceApiKey.value;
-}
-
 function hasMTLSClient(req) {
     try {
         const cert = req.socket?.getPeerCertificate?.(true);
@@ -81,15 +71,12 @@ function timingSafeCompare(a, b) {
 /**
  * For mutating API Portal REST routes: cookie-based sessions must send X-CSRF-Token
  * matching getSessionCsrfToken. Skips when auth matches non-browser paths used by
- * enforceSecurity (Bearer, API key, mTLS).
+ * enforceSecurity (Bearer, mTLS).
  */
 function requireCsrfForMutatingApi(req, res, next) {
     if (hasBearerAuthorization(req)) {
         return next();
     }
-    if (hasConfiguredApiKey(req)) {
-        return next();
-    }
     if (hasMTLSClient(req)) {
         return next();
     }
diff --git a/portals/api-portal/src/middlewares/ensureAuthenticated.js b/portals/api-portal/src/middlewares/ensureAuthenticated.js
index 50f7451830..29daf7309c 100644
--- a/portals/api-portal/src/middlewares/ensureAuthenticated.js
+++ b/portals/api-portal/src/middlewares/ensureAuthenticated.js
@@ -97,8 +97,6 @@ function enforceSecurity(scope) {
                 const decodedAccessToken = safeDecodeJwt(token);
                 req[constants.USER_ID] = await resolveUserUuid(req, decodedAccessToken?.[constants.USER_ID]);
                 return validateAuthentication(scope)(req, res, next);
-            } else if (config.security.serviceApiKey.enabled) {
-                enforceAPIKey(req, res, next);
             } else if (typeof req.socket?.getPeerCertificate === 'function' && req.socket.getPeerCertificate(true)) {
                 enforceMTLS(req, res, next);
             } else {
@@ -402,21 +400,6 @@ const enforceMTLS = (req, res, next) => {
     return next();
 };
 
-const enforceAPIKey = (req, res, next) => {
-    const keyType = config.security?.serviceApiKey?.headerName;
-
-    if (!keyType || !config.security?.serviceApiKey?.value) {
-        return res.status(500).json({ error: "Server configuration error" });
-    }
-
-    const apiKey = req.headers[keyType.toLowerCase()];
-
-    if (!apiKey || apiKey !== config.security?.serviceApiKey?.value) {
-        return res.status(401).json({ error: "Unauthorized: API key is invalid or not found" });
-    }
-    return next();
-};
-
 module.exports = {
     ensureAuthenticated,
     validateAuthentication,
diff --git a/portals/api-portal/src/middlewares/registerPartials.js b/portals/api-portal/src/middlewares/registerPartials.js
index e1d6dfda75..bec4917f7a 100644
--- a/portals/api-portal/src/middlewares/registerPartials.js
+++ b/portals/api-portal/src/middlewares/registerPartials.js
@@ -114,7 +114,14 @@ const registerPartials = async (req, res, next) => {
         notFound.status = 404;
         return next(notFound);
       }
-      next(error);
+      // Partial resolution reads per-view content, so a URL naming a view that
+      // doesn't exist surfaces here as a CustomError(404) — before any page
+      // controller runs. That status lives on `statusCode`, which the central
+      // handler doesn't read, so without this it rendered the 500 "Oops!" page
+      // instead of "Page not found". `return` matters too: falling through to
+      // the next() below would call next twice on the same request.
+      error.status = util.pageErrorStatus(error);
+      return next(error);
     }
   }
   next();
diff --git a/portals/api-portal/src/pages/application/partials/manage-keys-km-card.hbs b/portals/api-portal/src/pages/application/partials/manage-keys-km-card.hbs
index 5d4c901715..9f84ea7431 100644
--- a/portals/api-portal/src/pages/application/partials/manage-keys-km-card.hbs
+++ b/portals/api-portal/src/pages/application/partials/manage-keys-km-card.hbs
@@ -62,16 +62,17 @@
                     </div>
                 </div>
             </div>
-            {{!-- Revoke footer — part of Credentials tab --}}
+            {{!-- Remove-keys footer — part of Credentials tab --}}
             <div class="mk-km-footer" id="keyActionsContainer-{{keyType}}">
                 <span class="mk-secret-note">
                     <i class="bi bi-info-circle"></i>
-                    Revoking removes all credentials. Tokens already issued remain valid until they expire.
+                    Removing unlinks this client ID from the application. The OAuth client stays in the
+                    key manager, and tokens already issued remain valid until they expire.
                 </span>
                 <div class="mk-footer-actions">
                     <button class="mk-btn-danger"
-                        onclick="confirmAndRevokeKeys('{{appId}}', '{{keys.keyMappingId}}', '{{keyType}}')">
-                        <i class="bi bi-trash3"></i> Revoke keys
+                        onclick="confirmAndRemoveKeys('{{appId}}', '{{keys.keyMappingId}}', '{{keyType}}')">
+                        <i class="bi bi-trash3"></i> Remove keys
                     </button>
                 </div>
             </div>
diff --git a/portals/api-portal/src/pages/login-page/layout.hbs b/portals/api-portal/src/pages/login-page/layout.hbs
index 08bf54181e..e794392f9d 100644
--- a/portals/api-portal/src/pages/login-page/layout.hbs
+++ b/portals/api-portal/src/pages/login-page/layout.hbs
@@ -36,7 +36,7 @@
   <div class="auth-brand">
     <!-- Logo -->
     <div class="auth-logo-row">
-      <img class="auth-logo-svg" src="/images/api-portal-logo.svg" alt="API Portal &amp; MCP Hub" />
+      <img class="auth-logo-svg" src="/images/api-portal-logo-white.svg" alt="API Portal &amp; MCP Hub" />
     </div>
 
     <!-- Hero copy -->
diff --git a/portals/api-portal/src/pages/settings/partials/cfg-apis-panel.hbs b/portals/api-portal/src/pages/settings/partials/cfg-apis-panel.hbs
index a78d182db5..5d0b40e9aa 100644
--- a/portals/api-portal/src/pages/settings/partials/cfg-apis-panel.hbs
+++ b/portals/api-portal/src/pages/settings/partials/cfg-apis-panel.hbs
@@ -168,7 +168,7 @@
                 <div class="cfg-form-group">
                   <label for="wz-handle">Handle (URL slug) <span class="required">*</span></label>
                   <input type="text" id="wz-handle" class="cfg-form-input cfg-form-input--mono" placeholder="reading-list-api-v1.0" />
-                  <p class="cfg-field-hint">Auto-generated from name &amp; version. Edit to override.</p>
+                  <p class="cfg-field-hint">Auto-generated from name &amp; version. Edit to override — cannot be changed once created.</p>
                   <p id="wz-handle-error" style="display:none;color:#c62828;font-size:.75rem;margin:3px 0 0;"></p>
                 </div>
                 <div class="cfg-form-group">
@@ -193,7 +193,7 @@
                   </div>
                 </div>
                 <div class="cfg-form-group cfg-form-group-full">
-                  <label for="wz-desc">Description <span class="required">*</span></label>
+                  <label for="wz-desc">Description</label>
                   <textarea id="wz-desc" class="cfg-form-input" rows="3" placeholder="Describe what this API does in 1–2 sentences…"></textarea>
                   <p id="wz-desc-error" style="display:none;color:#c62828;font-size:.75rem;margin:3px 0 0;"></p>
                 </div>
diff --git a/portals/api-portal/src/pages/settings/partials/cfg-labels-panel.hbs b/portals/api-portal/src/pages/settings/partials/cfg-labels-panel.hbs
index 4425a27259..e9762a8aa2 100644
--- a/portals/api-portal/src/pages/settings/partials/cfg-labels-panel.hbs
+++ b/portals/api-portal/src/pages/settings/partials/cfg-labels-panel.hbs
@@ -14,8 +14,8 @@
           <table class="cfg-table">
             <thead>
               <tr>
-                <th>Display name</th>
                 <th>Name</th>
+                <th>Handle</th>
                 <th style="width:90px;"></th>
               </tr>
             </thead>
diff --git a/portals/api-portal/src/pages/settings/partials/cfg-modals.hbs b/portals/api-portal/src/pages/settings/partials/cfg-modals.hbs
index 02f388c60d..1ab8cb133c 100644
--- a/portals/api-portal/src/pages/settings/partials/cfg-modals.hbs
+++ b/portals/api-portal/src/pages/settings/partials/cfg-modals.hbs
@@ -98,13 +98,13 @@
       <button type="button" class="cfg-modal-close" id="cfg-label-modal-close"><i class="bi bi-x-lg"></i></button>
     </div>
     <div class="cfg-form-group" style="margin-bottom:16px;">
-      <label for="lbl-display">Display name <span class="required">*</span></label>
+      <label for="lbl-display">Name <span class="required">*</span></label>
       <input type="text" id="lbl-display" class="cfg-form-input" placeholder="e.g. Public" />
     </div>
     <div class="cfg-form-group" style="margin-bottom:24px;">
-      <label for="lbl-name">Name <span class="required">*</span></label>
+      <label for="lbl-name">Handle <span class="required">*</span></label>
       <input type="text" id="lbl-name" class="cfg-form-input cfg-form-input--mono" placeholder="public" />
-      <p class="cfg-field-hint">Lowercase identifier used internally.</p>
+      <p class="cfg-field-hint">Lowercase identifier used internally. Cannot be changed.</p>
     </div>
     <div class="cfg-modal-actions">
       <button type="button" class="cfg-btn-secondary" id="cfg-label-modal-cancel">Cancel</button>
diff --git a/portals/api-portal/src/pages/settings/partials/cfg-webhook-form.hbs b/portals/api-portal/src/pages/settings/partials/cfg-webhook-form.hbs
index 628b6924f5..f0bcf41d31 100644
--- a/portals/api-portal/src/pages/settings/partials/cfg-webhook-form.hbs
+++ b/portals/api-portal/src/pages/settings/partials/cfg-webhook-form.hbs
@@ -15,9 +15,14 @@
 
         <div class="cfg-webhook-form">
           <div class="cfg-form-group" style="margin-bottom:16px;">
-            <label for="wh-display">Display name <span class="required">*</span></label>
+            <label for="wh-display">Name <span class="required">*</span></label>
             <input type="text" id="wh-display" class="cfg-form-input" placeholder="e.g. Production listener" />
           </div>
+          <div class="cfg-form-group" style="margin-bottom:16px;">
+            <label for="wh-handle">Handle <span class="required">*</span></label>
+            <input type="text" id="wh-handle" class="cfg-form-input cfg-form-input--mono" placeholder="production-listener" />
+            <p class="cfg-field-hint">Identifier used in the API path. Cannot be changed.</p>
+          </div>
           <div class="cfg-form-group" style="margin-bottom:16px;">
             <label for="wh-url">Target URL <span class="required">*</span></label>
             <input type="text" id="wh-url" class="cfg-form-input cfg-form-input--mono" placeholder="https://example.com/webhook" />
diff --git a/portals/api-portal/src/pages/settings/partials/cfg-webhooks-panel.hbs b/portals/api-portal/src/pages/settings/partials/cfg-webhooks-panel.hbs
index f42c2ec56d..ae5a88a0da 100644
--- a/portals/api-portal/src/pages/settings/partials/cfg-webhooks-panel.hbs
+++ b/portals/api-portal/src/pages/settings/partials/cfg-webhooks-panel.hbs
@@ -18,7 +18,8 @@
           <table class="cfg-table">
             <thead>
               <tr>
-                <th>Display name</th>
+                <th>Name</th>
+                <th>Handle</th>
                 <th>Target URL</th>
                 <th>Events</th>
                 <th>Secret</th>
@@ -33,6 +34,7 @@
                   <button type="button" class="cfg-webhook-edit-btn" data-id="{{id}}"
                     style="border:none;background:none;padding:0;cursor:pointer;font-size:.875rem;font-weight:600;color:#1a2433;text-decoration:none;">{{displayName}}</button>
                 </td>
+                <td><span class="cfg-name-chip">{{id}}</span></td>
                 <td>
                   <span class="cfg-name-chip" title="{{targetUrl}}"
                     style="display:inline-block;max-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;">{{targetUrl}}</span>
@@ -60,7 +62,7 @@
               </tr>
               {{/webhookSubscribers}}
               {{#unless webhookSubscribers.length}}
-              <tr><td colspan="6" class="cfg-tbl-empty">No webhooks yet. Add one to get started.</td></tr>
+              <tr><td colspan="7" class="cfg-tbl-empty">No webhooks yet. Add one to get started.</td></tr>
               {{/unless}}
             </tbody>
           </table>
diff --git a/portals/api-portal/src/scripts/oauth2-key-generation.js b/portals/api-portal/src/scripts/oauth2-key-generation.js
index 86f1d4f796..f8041ea12b 100644
--- a/portals/api-portal/src/scripts/oauth2-key-generation.js
+++ b/portals/api-portal/src/scripts/oauth2-key-generation.js
@@ -58,13 +58,17 @@ async function addClientId(kmId, keyType, appId, orgId, keyManager) {
     }
 }
 
-function confirmAndRevokeKeys(applicationId, keyMappingId, keyType) {
+function confirmAndRemoveKeys(applicationId, keyMappingId, keyType) {
     const modal = document.getElementById('deleteConfirmation');
     if (modal) {
         const titleEl = modal.querySelector('.modal-title');
         const msgEl = modal.querySelector('.modal-message');
-        if (titleEl) titleEl.textContent = 'Revoke Application Keys';
-        if (msgEl) msgEl.textContent = 'Are you sure you want to remove this client ID? Tokens already issued remain valid until they expire.';
+        if (titleEl) titleEl.textContent = 'Remove Application Keys';
+        // Wording tracks what DELETE /applications/{id}/oauth-keys/{keyMappingId}
+        // actually does (see the operation description in the OpenAPI spec): it drops
+        // the portal's local client_id mapping only. The OAuth client itself is owned
+        // by the key manager and is untouched, as are tokens already issued from it.
+        if (msgEl) msgEl.textContent = 'Are you sure you want to unlink this client ID from the application? The OAuth client remains in the key manager, and tokens already issued remain valid until they expire.';
         modal.dataset.applicationId = applicationId;
         modal.dataset.param2 = keyMappingId;
 
@@ -74,7 +78,7 @@ function confirmAndRevokeKeys(applicationId, keyMappingId, keyType) {
             confirmBtn.removeEventListener('click', handler);
             if (confirmBtn) {
                 confirmBtn.disabled = true;
-                confirmBtn.innerHTML = '<span class="spinner-border spinner-border-sm" role="status"></span> Revoking…';
+                confirmBtn.innerHTML = '<span class="spinner-border spinner-border-sm" role="status"></span> Removing…';
             }
             await removeApplicationKeys(applicationId, keyMappingId, keyType);
             if (confirmBtn) {
@@ -86,7 +90,7 @@ function confirmAndRevokeKeys(applicationId, keyMappingId, keyType) {
 
         const bsModal = new bootstrap.Modal(modal);
         bsModal.show();
-    } else if (confirm('Are you sure you want to remove this client ID? This cannot be undone.')) {
+    } else if (confirm('Are you sure you want to unlink this client ID from the application? The OAuth client remains in the key manager.')) {
         removeApplicationKeys(applicationId, keyMappingId, keyType);
     }
 }
diff --git a/portals/api-portal/src/scripts/settings-apis.js b/portals/api-portal/src/scripts/settings-apis.js
index 254f884664..60e91063e3 100644
--- a/portals/api-portal/src/scripts/settings-apis.js
+++ b/portals/api-portal/src/scripts/settings-apis.js
@@ -263,6 +263,10 @@
       document.getElementById('cfg-wizard-title').textContent = isMcp ? 'Edit MCP Server' : 'Edit API';
       sv('wz-name',       api.apiName);
       sv('wz-handle',     api.apiHandle);   handleTouched = true;
+      /* The handle is the API's identity in every portal URL and apiDao.update
+         never writes it — leaving the field editable let a change look accepted
+         while being silently discarded. */
+      document.getElementById('wz-handle').readOnly = true;
       sv('wz-version',    api.apiVersion);
       sel('wz-type',      api.apiType);
       sel('wz-status',    api.apiStatus === 'DEPRECATED' ? 'DEPRECATED' : 'PUBLISHED');
@@ -286,6 +290,7 @@
       editingId = null;
       document.getElementById('cfg-wizard-title').textContent = isMcp ? 'Add MCP Server' : 'Add API';
       ['wz-name','wz-version','wz-handle','wz-desc','wz-tags','wz-prod','wz-sandbox','wz-tech-owner','wz-tech-email','wz-biz-owner','wz-biz-email'].forEach(function(id){ sv(id,''); });
+      document.getElementById('wz-handle').readOnly = false;
       sel('wz-type', isMcp ? 'Mcp' : 'RestApi'); sel('wz-status','PUBLISHED');
       agentVis = 'Visible';
       document.getElementById('wz-vis-visible').classList.add('active');
@@ -680,9 +685,9 @@
     setFieldError('wz-version', 'wz-version-error', version ? '' : 'Version is required.');
     if (!version) ok = false;
 
-    var desc = v('wz-desc');
-    setFieldError('wz-desc', 'wz-desc-error', desc ? '' : 'Description is required.');
-    if (!desc) ok = false;
+    // Description is optional — api_metadata.description is nullable and the
+    // create/update API never required it.
+    setFieldError('wz-desc', 'wz-desc-error', '');
 
     var handle = v('wz-handle');
     if (!handle) {
diff --git a/portals/api-portal/src/scripts/settings-labels.js b/portals/api-portal/src/scripts/settings-labels.js
index 7f82fcf303..9cbc063e73 100644
--- a/portals/api-portal/src/scripts/settings-labels.js
+++ b/portals/api-portal/src/scripts/settings-labels.js
@@ -34,12 +34,15 @@
     document.getElementById('cfg-label-modal-save').textContent  = mode === 'edit' ? 'Save changes' : 'Add label';
     document.getElementById('lbl-display').value = mode === 'edit' ? data.displayName : '';
     document.getElementById('lbl-name').value    = mode === 'edit' ? data.id          : '';
+    /* The handle is the label's identity — every API and view mapping keys off
+       it, so it cannot change after creation. */
+    document.getElementById('lbl-name').readOnly = mode === 'edit';
     document.getElementById('cfg-label-modal').style.display = 'flex';
     document.getElementById('lbl-display').focus();
   }
   function closeLabelModal() { document.getElementById('cfg-label-modal').style.display = 'none'; editLabelName = null; }
 
-  /* ── auto-slug display → name (skips once the user edits Name) ── */
+  /* ── auto-slug name → handle (skips once the user edits Handle) ── */
   document.getElementById('lbl-name').addEventListener('input', function() { labelHandleTouched = true; });
   document.getElementById('lbl-display').addEventListener('input', function() {
     if (editLabelName || labelHandleTouched) return;
@@ -50,26 +53,20 @@
   document.getElementById('cfg-label-modal-save').addEventListener('click', async function() {
     var displayName = v('lbl-display');
     var name        = v('lbl-name');
-    if (!displayName || !name) { await showAlert('Display name and name are required.', 'error'); return; }
+    if (!displayName || !name) { await showAlert('Name and handle are required.', 'error'); return; }
 
     try {
       var res;
-      if (editLabelName && editLabelName !== name) {
-        /* handle changed — handle is immutable, so delete old and create new */
-        await fetch(window.apiPortalApi.root('/labels/'+encodeURIComponent(editLabelName)), {
-          method: 'DELETE',
-          headers: { 'X-CSRF-Token': window.apiPortalApi.csrfToken() },
-        });
-        res = await fetch(window.apiPortalApi.root('/labels'), {
-          method: 'POST',
-          headers: { 'Content-Type':'application/json', 'X-CSRF-Token': window.apiPortalApi.csrfToken() },
-          body: JSON.stringify({ id: name, displayName: displayName }),
-        });
-      } else if (editLabelName) {
-        res = await fetch(window.apiPortalApi.root('/labels/'+encodeURIComponent(name)), {
+      if (editLabelName) {
+        /* Handle is immutable and the input is read-only while editing, so this
+           is always a display-name update. It used to fall back to DELETE + POST
+           when the handle differed — but deleting a label cascades through
+           api_label_mappings / view_label_mappings, so every API and view lost
+           the label and the recreated one came back with no members. */
+        res = await fetch(window.apiPortalApi.root('/labels/'+encodeURIComponent(editLabelName)), {
           method: 'PUT',
           headers: { 'Content-Type':'application/json', 'X-CSRF-Token': window.apiPortalApi.csrfToken() },
-          body: JSON.stringify({ id: name, displayName: displayName }),
+          body: JSON.stringify({ id: editLabelName, displayName: displayName }),
         });
       } else {
         res = await fetch(window.apiPortalApi.root('/labels'), {
diff --git a/portals/api-portal/src/scripts/settings-organization.js b/portals/api-portal/src/scripts/settings-organization.js
index 71c67e7fce..382f463219 100644
--- a/portals/api-portal/src/scripts/settings-organization.js
+++ b/portals/api-portal/src/scripts/settings-organization.js
@@ -48,7 +48,10 @@
     var owner = g('org-owner').value.trim();         if (owner) body.businessOwner = owner;
     var oc    = g('org-owner-contact').value.trim(); if (oc)    body.businessOwnerContact = oc;
     if (oe) body.businessOwnerEmail = oe;
-    var cp    = g('org-cp-ref').value.trim();         if (cp)    body.cpRefId = cp;
+    // Always sent, blank included — same as idpRefId above. orgDao.update writes
+    // cp_ref_id unconditionally, so omitting a cleared field would leave the old
+    // value in place and make the reference impossible to remove from this form.
+    body.cpRefId = g('org-cp-ref').value.trim();
     saveBtn.disabled = true;
     try {
       var res = await fetch(window.apiPortalApi.root('/organizations/' + encodeURIComponent(handle)), {
diff --git a/portals/api-portal/src/scripts/settings-webhooks.js b/portals/api-portal/src/scripts/settings-webhooks.js
index 82e39ef273..f2d7039227 100644
--- a/portals/api-portal/src/scripts/settings-webhooks.js
+++ b/portals/api-portal/src/scripts/settings-webhooks.js
@@ -25,6 +25,7 @@
   // field means "keep the stored one", so the mandatory check below only applies when
   // there is nothing stored to keep — on create, or on a legacy row saved without one.
   var editHasSecret = false;
+  var handleTouched = false;
 
   function v(id) { var e=document.getElementById(id); return e?e.value.trim():''; }
 
@@ -113,9 +114,14 @@
   function showWebhookForm(mode, data) {
     editWebhookId = mode === 'edit' ? data.id : null;
     editHasSecret = mode === 'edit' && !!data.hasSecret;
+    handleTouched = false;
     document.getElementById('wh-form-title').textContent = mode === 'edit' ? 'Edit webhook' : 'Add webhook';
     document.getElementById('wh-form-save').textContent  = mode === 'edit' ? 'Save changes' : 'Add webhook';
     document.getElementById('wh-display').value   = mode === 'edit' ? (data.displayName || '') : '';
+    document.getElementById('wh-handle').value    = mode === 'edit' ? (data.id || '') : '';
+    /* The handle is the subscriber's identity and the id in its API path, so it
+       is fixed once created. */
+    document.getElementById('wh-handle').readOnly = mode === 'edit';
     document.getElementById('wh-url').value       = mode === 'edit' ? (data.targetUrl || '')       : '';
     document.getElementById('wh-secret').value    = '';
     document.getElementById('wh-timeout').value   = mode === 'edit' ? (data.timeoutMs || 5000) : 5000;
@@ -137,11 +143,25 @@
     editHasSecret = false;
   }
 
+  /* ── auto-slug name → handle (skips once the user edits Handle, or on edit) ── */
+  var whHandleRe = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+  document.getElementById('wh-handle').addEventListener('input', function() { handleTouched = true; });
+  document.getElementById('wh-display').addEventListener('input', function() {
+    if (editWebhookId || handleTouched) return;
+    document.getElementById('wh-handle').value =
+      this.value.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  });
+
   /* ── save ── */
   document.getElementById('wh-form-save').addEventListener('click', async function() {
     var displayName = v('wh-display');
+    var handle      = v('wh-handle');
     var url         = v('wh-url');
-    if (!displayName || !url) { await showAlert('Display name and target URL are required.', 'error'); return; }
+    if (!displayName || !handle || !url) { await showAlert('Name, handle and target URL are required.', 'error'); return; }
+    if (!whHandleRe.test(handle)) {
+      await showAlert('Handle must be lowercase letters, numbers and hyphens only.', 'error');
+      return;
+    }
 
     // The secret both signs deliveries and encrypts sensitive event fields, so a
     // subscriber without one silently loses the API key / token payloads entirely.
@@ -172,9 +192,6 @@
       return;
     }
 
-    // No `id`: the server derives the handle from displayName on create, and omitting
-    // it on update leaves the existing handle untouched (the DAO patches sparsely).
-    // Sending one here would silently rename the subscriber on every save.
     var body = {
       displayName: displayName,
       targetUrl: url,
@@ -182,6 +199,11 @@
       enabled: document.getElementById('wh-enabled').checked,
       timeoutMs: timeoutMs,
     };
+    // `id` only on create — that is the caller-chosen handle, and the server
+    // falls back to a random UUID when it is absent. On update it is omitted
+    // deliberately: the handle is immutable, and the DAO patches sparsely, so
+    // sending one would rename the subscriber on every save.
+    if (!editWebhookId) body.id = handle;
     var secret = v('wh-secret');
     if (secret) body.secret = secret;
 
diff --git a/portals/api-portal/src/services/apiMetadataService.js b/portals/api-portal/src/services/apiMetadataService.js
index 4be25b2fb7..f36e1a4628 100644
--- a/portals/api-portal/src/services/apiMetadataService.js
+++ b/portals/api-portal/src/services/apiMetadataService.js
@@ -1620,26 +1620,36 @@ const getOrgLabels = async (orgId) => {
 const addView = async (req, res) => {
 
     const orgId = req.orgId;
-    const labels = req.body.labels;
+    // labels is optional — a view with none is valid, it just surfaces no APIs
+    // until labels are attached later. getLabelId() iterates the list, so an
+    // absent one has to become [] here rather than reaching the DAO undefined.
+    const labels = Array.isArray(req.body.labels) ? req.body.labels : [];
     const userId = util.resolveActor(req);
     if (req.body.id) {
         req.body.handle = req.body.id;
     }
-    await db.withTransaction(async (t) => {
-        try {
+    try {
+        await db.withTransaction(async (t) => {
             const viewResponse = await viewDao.create(orgId, req.body, userId, t);
-            const viewId = viewResponse.uuid;
-            await viewDao.addLabels(orgId, viewId, labels, userId, t);
-            res.status(201).send({ message: "View added successfully" });
-        } catch (error) {
-            logger.error('view create error failed', {
-                error: error.message,
-                stack: error.stack,
-                orgId
-            });
-            util.handleError(res, error);
-        }
-    });
+            await viewDao.addLabels(orgId, viewResponse.uuid, labels, userId, t);
+        });
+        // Responded to only after the transaction has COMMITTED. Sending from inside
+        // the callback is wrong twice over: a client that reads the view back can beat
+        // the commit it was just told succeeded (visible on Postgres, where the read
+        // takes a different pooled connection and cannot see uncommitted rows), and a
+        // COMMIT that then fails leaves the caller holding a 2xx for work that was
+        // rolled back. The catch also has to live out here — inside the callback it
+        // swallowed the error, so withTransaction saw the callback resolve and
+        // committed the partial write instead of rolling it back.
+        res.status(201).send({ message: "View added successfully" });
+    } catch (error) {
+        logger.error('view create error failed', {
+            error: error.message,
+            stack: error.stack,
+            orgId
+        });
+        util.handleError(res, error);
+    }
 }
 
 const updateView = async (req, res) => {
@@ -1663,8 +1673,13 @@ const updateView = async (req, res) => {
             }
             viewId = viewId ? viewId : await viewDao.getId(orgId, viewHandle, t);
             updatedViewId = viewId;
-            res.status(200).send(req.body);
         });
+        // After COMMIT, not inside the callback — see the note in addView. This is
+        // what the "updates a view" spec's read-back depends on: it GETs the view
+        // immediately after this 200, and on Postgres that read runs on a different
+        // pooled connection, so a response sent pre-commit can be answered from the
+        // pre-update snapshot.
+        res.status(200).send(req.body);
         // Fired only after the transaction above has committed and released its
         // connection — see the comment in updateAPIMetadata for why firing this
         // while the connection is still checked out deadlocks against itself.
diff --git a/portals/api-portal/src/styles/settings-layout.css b/portals/api-portal/src/styles/settings-layout.css
index 1e870482c9..40030b2fc7 100644
--- a/portals/api-portal/src/styles/settings-layout.css
+++ b/portals/api-portal/src/styles/settings-layout.css
@@ -599,6 +599,25 @@
 
 .cfg-form-input--mono { font-family: var(--font-family-mono); font-size: 0.8125rem; }
 
+/* Read-only fields — handles, and values the operator sets elsewhere. A handle is
+   a resource's identity and is immutable after creation, so the field must not
+   look typeable. Attribute selector (0,2,0) outranks .cfg-form-input (0,1,0),
+   including the :focus rule above, which is overridden explicitly below. */
+.cfg-form-input[readonly] {
+  background: var(--surface-sunken);
+  color: var(--text-muted);
+  cursor: not-allowed;
+}
+
+/* A read-only input is still keyboard-focusable (unlike a disabled one), so it keeps
+   a focus ring — just a muted one, so it reads as "focused but not editable" rather
+   than borrowing the primary-coloured ring of a field you can type into. Suppressing
+   the indicator entirely left keyboard users with no way to see where focus was. */
+.cfg-form-input[readonly]:focus {
+  border-color: var(--border-strong);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--text-muted) 22%, transparent);
+}
+
 /* ── File upload zone ────────────────────────────────────── */
 
 .cfg-upload-zone {
diff --git a/portals/api-portal/src/utils/util.js b/portals/api-portal/src/utils/util.js
index a8a22cc5bb..1bb416e3dd 100644
--- a/portals/api-portal/src/utils/util.js
+++ b/portals/api-portal/src/utils/util.js
@@ -342,6 +342,20 @@ function getErrors(errors) {
     return errorList;
 }
 
+// Page controllers hand the central error handler (src/app.js) a status on
+// `error.status`, but a DAO-level CustomError carries its HTTP status on
+// `statusCode` instead. Forcing 500 in every catch turned a genuinely
+// client-side failure — most visibly a URL naming a view that doesn't exist,
+// where viewDao.getId throws CustomError(404) — into the "Oops! Something went
+// wrong" 500 page. Preserve only the statuses the error page actually renders;
+// anything else really is a 500.
+const PAGE_ERROR_STATUSES = new Set([400, 403, 404]);
+
+function pageErrorStatus(error) {
+    const status = error?.statusCode ?? error?.status;
+    return PAGE_ERROR_STATUSES.has(status) ? status : 500;
+}
+
 function handleError(res, error) {
     if (db.isDuplicateKeyError(error)) {
         // Raw driver messages (pg/sqlite/mssql) can echo internal constraint/table
@@ -1357,6 +1371,7 @@ module.exports = {
     renderLlmsTxt,
     renderGivenTemplate,
     handleError,
+    pageErrorStatus,
     sendError,
     retrieveContentType,
     getAPIFileContent,