API Portal ↔ Platform-API — Internal Shared-Key Auth

[dushaniw]

What

Platform-API's publishing calls to the API Portal admin REST APIs (publish / update / delete API, API content, MCP Server, MCP Server content, Subscription Plan) authenticate with a shared secret — a 256-bit random key.

• API Portal stores only sha256(key).
• Platform-API keeps the raw and sends Authorization: SharedKey <raw> — a custom auth scheme (RFC 7235), not the OAuth 2.0 Bearer scheme.
• Ownership: API Portal generates the key at bootstrap; the operator hands the raw to Platform-API once at portal registration. After that, no key material appears in any REST request or response.

Covers only Platform-API's S2S publishing path. Consumer login (portal UI) is untouched — shared-key middleware is additive and scoped to specific admin handlers.

Flow

1. Operator runs portals/scripts/setup.sh
   → writes sha256(raw) to /etc/api-portal/keys/api-portal-internal-key-hash
   → writes raw to    /etc/api-portal/keys/api-portal-internal-key.raw (0600)
   → stdout prints the file path, NOT the raw

2. Operator reads the raw from the file, then calls:
     POST /api-portals  { name, handle, url, sharedKey: "<raw>" }
   Platform-API stores the raw encrypted; response does not echo it.

3. Operator: rm .../api-portal-internal-key.raw

4. API Portal boots, loads the hash via the existing {{ file "..." }}
   toml interpolation.

5. Every publishing call:
     Authorization: SharedKey <raw>
   Middleware dispatches by scheme name: SharedKey → sha256 the raw,
   constant-time compare vs the stored hash, synthesise platform-api-system
   principal on match; Bearer → fall through to the existing OAuth verifier;
   anything else → 401.

Changes

API Portal

• Setup script. Extend portals/scripts/setup.sh — same shape as the existing encryption_key / session_secret generation: openssl rand -hex 32, write hash and raw to separate files, idempotent (skip if hash file exists). New flags: --force, --rotate-internal-key.
• Config. New section in portals/api-portal/configs/config.toml:

  [api_portal.internal_auth]
  hash_path = '{{ file "/etc/api-portal/keys/api-portal-internal-key-hash" }}'

• Middleware. Wrap the 15 mutating admin operation handlers (create / update / delete × 5 resources) via the existing compose() utility — same scoping pattern already used for CSRF middleware. Middleware dispatches by Authorization scheme name: SharedKey → hash + constant-time compare, synthesise platform-api-system principal on match; Bearer → fall through to the existing OAuth verifier; anything else → 401. UI / login routes live on separate page routers, automatically unaffected. There is no URL-prefix split between admin and consumer routes today — scoping must be per-handler, not per-route.
• Audit logs. For shared-key calls, log first 8 hex chars of the loaded hash as the principal — never the incoming raw.

Platform-API

• Storage. internal_auth_secret BYTEA column on api_portals, holding the encrypted raw. Reuses the existing at-rest encryption key path platform-api already uses for other credentials. No per-portal auth_type column — shared-key is the only S2S mechanism.
• REST contract. :
  • POST /api-portals: sharedKey: "<raw>" required in the request body (hex string, 64 chars). Response never echoes it.
  • PUT /api-portals/{id}: sharedKey optional; if present, replaces the stored value (rotation path).
  • GET endpoints: never return key material.

Rotation

Customer-driven. No dedicated endpoint.

1. portals/scripts/setup.sh --rotate-internal-key → new raw + hash.
2. Restart the API Portal.
3. Read the new raw, call PUT /api-portals/{id} with the new sharedKey.
4. rm the raw file.

Between (2) and (3) Platform-API's publishing calls with the old raw will 401. Order matters: rotate the API Portal first, then update Platform-API, then delete the file.

[dushaniw]

cc @malinthaprasan @pubudu538 @lasanthaS