[Devportal] Update quick start and other docs

portals/developer-portal/README.md

@@ -285,7 +285,7 @@ Create an API manifest file and an OpenAPI definition, then upload them:
 
 ```yaml
 # api.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: RestApi
 
 metadata:
@@ -404,7 +404,7 @@ paths:
 ```bash
 # Get a Bearer token (substitute the credentials ./scripts/setup.sh printed)
 TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
-  -d "username=admin&password=admin" | jq -r .token)
+  -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 
 # Get the default org UUID
 ORG_ID=$(curl -sk -H "Authorization: Bearer $TOKEN" \

portals/developer-portal/docs/administer/design-mode.md

@@ -137,7 +137,7 @@ zip -r my-theme.zip layout/ partials/ styles/ images/
 **Option 2 — curl:** Replace `{viewName}` with the view name (e.g. `default`). The examples use a `$TOKEN` variable — get one first:
 ```bash
 TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
-  -d "username=admin&password=admin" | jq -r .token)
+  -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 ```
 
 Initial upload:
@@ -186,7 +186,7 @@ samples/
 ### `api.yaml` Format (REST API)
 
 ```yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: RestApi
 
 metadata:
@@ -214,7 +214,7 @@ spec:
 ### `api.yaml` Format (MCP Server)
 
 ```yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: MCP
 
 metadata:
@@ -261,7 +261,7 @@ The portal re-reads API definitions from disk on every page request. Edit `api.y
 The Applications page is available in design mode and shows entries from `applications_path`. The format follows the same Kubernetes-style manifest used across all sample files:
 
 ```yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: ApplicationList
 items:
 

portals/developer-portal/docs/administer/key-manager-integration.md

@@ -11,14 +11,14 @@ No encryption key is required for key manager configuration — the portal never
 > **Authentication:** The examples below use a `$TOKEN` variable. Obtain a Bearer token first:
 > ```bash
 > TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
->   -d "username=admin&password=admin" | jq -r .token)
+>   -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 > ```
 
 Use the `KeyManager` manifest format:
 
 ```yaml
 # keymanager.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: KeyManager
 
 metadata:
@@ -61,7 +61,7 @@ curl -k https://localhost:3000/api/v0.9/key-managers/{kmId} -H "Authorization: B
 
 ```yaml
 # keymanager-update.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: KeyManager
 
 metadata:

portals/developer-portal/docs/administer/manage-organizations.md

@@ -8,7 +8,7 @@ Create an `org.yaml` file using the Organization manifest format:
 
 ```yaml
 # org.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: Organization
 
 metadata:
@@ -63,7 +63,7 @@ curl -k https://localhost:3000/api/v0.9/organizations -H "Authorization: Bearer
 
 ```yaml
 # org-update.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: Organization
 
 metadata:
@@ -104,7 +104,7 @@ For local development and first-time setup, the portal ships with a built-in use
 
 ### Configuration
 
-Users and their scopes are defined in `configs/config-platform-api.toml`. Copy the template file to get started:
+Users and their scopes are defined in `configs/config-platform-api.toml`. Running `./scripts/setup.sh` (see the [Quick Start](../introduction/quick-start.md)) generates this file with a single admin user. To edit it by hand — or to create a static, no-dependencies starting point without the setup script — copy the template instead:
 
 ```bash
 cp configs/config-platform-api-template.toml configs/config-platform-api.toml
@@ -155,7 +155,7 @@ For scripts and CLI tools, get a Bearer token directly from the Platform API and
 
 ```bash
 TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
-  -d "username=admin&password=admin" | jq -r .token)
+  -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 
 curl -sk -H "Authorization: Bearer $TOKEN" https://localhost:3000/api/v0.9/organizations
 ```

portals/developer-portal/docs/administer/manage-views.md

@@ -13,7 +13,7 @@ https://<host>/<orgHandle>/views/<viewName>
 > **Authentication:** The examples below use a `$TOKEN` variable. Obtain a Bearer token first:
 > ```bash
 > TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
->   -d "username=admin&password=admin" | jq -r .token)
+>   -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 > ```
 
 ```json

portals/developer-portal/docs/administer/subscription-plans.md

@@ -25,14 +25,14 @@ You can create additional custom plans alongside these defaults.
 > **Authentication:** The examples below use a `$TOKEN` variable. Obtain a Bearer token first:
 > ```bash
 > TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
->   -d "username=admin&password=admin" | jq -r .token)
+>   -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 > ```
 
 Use the `SubscriptionPlan` manifest format:
 
 ```yaml
 # plan.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: SubscriptionPlan
 
 metadata:
@@ -65,7 +65,7 @@ To create multiple plans in one request, use the `SubscriptionPlanList` kind:
 
 ```yaml
 # plans.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: SubscriptionPlanList
 
 items:
@@ -111,7 +111,7 @@ curl -k https://localhost:3000/api/v0.9/subscription-plans/{planId} \
 
 ```yaml
 # plan-update.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: SubscriptionPlan
 
 metadata:

portals/developer-portal/docs/introduction/quick-start.md

@@ -5,7 +5,8 @@ Get the Developer Portal running locally in a few minutes using Docker Compose.
 ## Prerequisites
 
 - [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/) installed
-- Port 3000 available
+- `openssl` on your `PATH` (used by the setup script to generate certs and secrets)
+- Ports 3000 (Developer Portal) and 9243 (Platform API) available
 
 ## Steps
 
@@ -16,17 +17,23 @@ git clone https://github.com/wso2/api-platform.git
 cd api-platform/portals/developer-portal/
 ```
 
-### 2. Create configuration files
-
-Copy both sample configuration files:
+### 2. Run the setup script
 
 ```bash
-mkdir -p configs
-cp configs/config.toml.example configs/config.toml
-cp configs/config-platform-api-template.toml configs/config-platform-api.toml
+./scripts/setup.sh
 ```
 
-`config.toml` controls the Developer Portal itself. `config-platform-api.toml` configures the Platform API sidecar that validates login credentials and issues signed tokens. The default credentials in the example file are `admin` / `admin`.
+This one-time script provisions everything the containers need to start:
+
+- a self-signed TLS certificate under `resources/certificates/`
+- the Developer Portal's encryption/session secrets and the shared JWT signing key, written to `api-platform.env`
+- `configs/config-platform-api.toml` — the config for the Platform API sidecar that validates login credentials and issues signed tokens
+
+It also prompts you for an **admin username and password**. Press Enter at the password prompt to have a strong one generated for you — it is printed once at the end, so copy it before continuing. The credentials are stored bcrypt-hashed in `api-platform.env`.
+
+`config.toml`, which controls the Developer Portal itself, is already present in `configs/` — no copying needed.
+
+> The script is idempotent: re-running it only fills in what's missing and never overwrites an existing value. To rotate a secret, remove it from `api-platform.env` (or delete `resources/certificates/` for the TLS cert) and re-run.
 
 ### 3. Start the portal
 
@@ -44,17 +51,31 @@ Navigate to:
 https://localhost:3000/default/views/default
 ```
 
-Sign in with `admin` / `admin` (the credentials defined in `configs/config-platform-api.toml`).
+Sign in with the admin username and password you set when running `./scripts/setup.sh`.
+
+You should see the default API catalog page. It stays empty until you add APIs — either seed the bundled samples (next step) or publish your own (the step after).
+
+### 5. Seed sample APIs (optional)
+
+The fastest way to see a populated catalog is to deploy the bundled sample APIs and MCP servers:
+
+```bash
+./scripts/seed-samples.sh
+```
+
+This deploys everything under `samples/` into the `default` organization through the public REST API (the portal has no built-in seeding logic). It prompts for the admin username and password you set in step 2 — or set `ADMIN_USERNAME` / `ADMIN_PASSWORD` to skip the prompt. Safe to re-run: samples that already exist (matched by name and version) are skipped.
+
+> Requires `curl`, `jq`, and `zip` on your `PATH`. The portal must be running (step 3). Set `DEVPORTAL_URL` / `PLATFORM_API_URL` to override the defaults (`https://localhost:3000` / `https://localhost:9243`).
 
-You should see the default API catalog page, empty until you publish an API (next step) or run `./scripts/seed-samples.sh` to deploy a set of ready-made sample APIs/MCPs.
+Refresh the catalog page and the sample APIs appear. To publish an API of your own instead, continue below.
 
-### 5. Publish your first API
+### 6. Publish your first API
 
 Create an API manifest file and an OpenAPI definition, then upload them:
 
 ```yaml
 # api.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: RestApi
 
 metadata:
@@ -174,15 +195,15 @@ Scripts and CLI tools authenticate with a Bearer token obtained directly from th
 
 ```bash
 # Get a token from the Platform API (runs alongside the devportal).
-# Login uses the file-based credentials from the Platform API config.
+# Use the admin credentials you set when running ./scripts/setup.sh.
 TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
-  -d "username=admin&password=admin" | jq -r .token)
+  -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 
 # Publish the API (the token's org_handle claim scopes this to the "default" org)
 curl -sk -X POST "https://localhost:3000/api/v0.9/apis" \
   -H "Authorization: Bearer $TOKEN" \
-  -F "api=@api.yaml;type=application/yaml" \
-  -F "apiDefinition=@openapi.yaml;type=application/yaml"
+  -F "metadata=@api.yaml;type=application/yaml" \
+  -F "definition=@openapi.yaml;type=application/yaml"
 ```
 
 Refresh the portal — the Ping API now appears in the catalog. Click it to view the documentation and try-out console.
@@ -194,7 +215,7 @@ Refresh the portal — the Ping API now appears in the catalog. Click it to view
 | Organization | `default` |
 | Default view | `default` |
 | Portal URL | `https://localhost:3000/default/views/default` |
-| Admin credentials | `admin` / `admin` (Platform API — see `configs/config-platform-api.toml`) |
+| Admin credentials | Set when you ran `./scripts/setup.sh` (stored bcrypt-hashed in `api-platform.env`) |
 | Sample API | `Ping API` visible in the catalog |
 
 ## Next steps

portals/developer-portal/docs/publish-apis/api-content-and-docs.md

@@ -29,7 +29,7 @@ At least one of `web/` or `docs/` must be present in the ZIP.
 > **Authentication:** The examples below use a `$TOKEN` variable. Obtain a Bearer token first:
 > ```bash
 > TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
->   -d "username=admin&password=admin" | jq -r .token)
+>   -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 > ```
 
 ```bash

portals/developer-portal/docs/publish-apis/manage-api-workflows.md

@@ -9,7 +9,7 @@ This page covers the admin API endpoints for managing workflows programmatically
 > **Authentication:** The examples below use a `$TOKEN` variable. Obtain a Bearer token first:
 > ```bash
 > TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
->   -d "username=admin&password=admin" | jq -r .token)
+>   -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 > ```
 
 ## Create a Workflow

portals/developer-portal/docs/publish-apis/publishing-apis.md

@@ -19,7 +19,7 @@ Create an API manifest file using the appropriate `kind`. The file **must** be n
 
 ```yaml
 # api.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: RestApi   # RestApi | WS | GraphQL | SOAP | WebSubApi
 
 metadata:
@@ -62,7 +62,7 @@ For an MCP server, use `mcp.yaml` instead:
 
 ```yaml
 # mcp.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: MCP
 
 metadata:
@@ -98,7 +98,7 @@ spec:
 > **Authentication:** The examples below use a `$TOKEN` variable. Obtain a Bearer token first:
 > ```bash
 > TOKEN=$(curl -sk -X POST "https://localhost:9243/api/portal/v0.9/auth/login" \
->   -d "username=admin&password=admin" | jq -r .token)
+>   -d "username=<admin-username>&password=<admin-password>" | jq -r .token)
 > ```
 
 Send the manifest and definition together as a multipart upload:
@@ -107,25 +107,25 @@ Send the manifest and definition together as a multipart upload:
 # REST API with OpenAPI definition
 curl -k -X POST "https://localhost:3000/api/v0.9/apis" \
   -H "Authorization: Bearer $TOKEN" \
-  -F "api=@api.yaml" \
-  -F "apiDefinition=@openapi.yaml;type=application/yaml"
+  -F "metadata=@api.yaml" \
+  -F "definition=@openapi.yaml;type=application/yaml"
 ```
 
 ```bash
 # GraphQL API
 curl -k -X POST "https://localhost:3000/api/v0.9/apis" \
   -H "Authorization: Bearer $TOKEN" \
-  -F "api=@api.yaml" \
-  -F "apiDefinition=@schema.graphql;type=application/graphql"
+  -F "metadata=@api.yaml" \
+  -F "definition=@schema.graphql;type=application/graphql"
 ```
 
 ```bash
 # MCP server (note: MCP servers are created under /mcp-servers, not /apis).
 # An MCP server's contract is its tools schema (schemaDefinition) — it has no apiDefinition.
 curl -k -X POST "https://localhost:3000/api/v0.9/mcp-servers" \
   -H "Authorization: Bearer $TOKEN" \
-  -F "api=@mcp.yaml" \
-  -F "schemaDefinition=@schemaDefinition.yaml;type=application/yaml"
+  -F "metadata=@mcp.yaml" \
+  -F "definition=@schemaDefinition.yaml;type=application/yaml"
 ```
 
 | Field | Required | Description |
@@ -156,17 +156,17 @@ The response includes the `apiId` needed for subsequent steps.
 curl -k -X PUT \
   "https://localhost:3000/api/v0.9/apis/{apiId}" \
   -H "Authorization: Bearer $TOKEN" \
-  -F 'apiMetadata={"id":"{apiId}","name":"Order API","endPoints":{"productionURL":"https://api.example.com/orders","sandboxURL":"https://sandbox.example.com/orders"}}' \
-  -F "apiDefinition=@openapi.yaml;type=application/yaml"
+  -F 'metadata={"id":"{apiId}","name":"Order API","endPoints":{"productionURL":"https://api.example.com/orders","sandboxURL":"https://sandbox.example.com/orders"}}' \
+  -F "definition=@openapi.yaml;type=application/yaml"
 ```
 
 ```bash
 # AsyncAPI YAML
 curl -k -X PUT \
   "https://localhost:3000/api/v0.9/apis/{apiId}" \
   -H "Authorization: Bearer $TOKEN" \
-  -F 'apiMetadata={"id":"{apiId}","name":"Order API","endPoints":{"productionURL":"https://api.example.com/orders","sandboxURL":"https://sandbox.example.com/orders"}}' \
-  -F "apiDefinition=@asyncapi.yaml;type=application/yaml"
+  -F 'metadata={"id":"{apiId}","name":"Order API","endPoints":{"productionURL":"https://api.example.com/orders","sandboxURL":"https://sandbox.example.com/orders"}}' \
+  -F "definition=@asyncapi.yaml;type=application/yaml"
 ```
 
 The uploaded definition is shown in the API's **Try-Out** tab and is exposed at the machine-readable spec endpoint for AI agent consumption.
@@ -286,7 +286,7 @@ Consumers subscribe to a plan (receiving a subscription token), generate an API
 
 ```yaml
 # api-update.yaml
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: RestApi
 
 metadata:
@@ -305,7 +305,7 @@ spec:
 ```bash
 curl -k -X PUT https://localhost:3000/api/v0.9/apis/{apiId} \
   -H "Authorization: Bearer $TOKEN" \
-  -F "api=@api-update.yaml"
+  -F "metadata=@api-update.yaml"
 ```
 
 ## Delete an API

portals/developer-portal/samples/apis/booking-api/api.yaml

@@ -1,4 +1,4 @@
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: RestApi
 
 metadata:

portals/developer-portal/samples/apis/catalog-api/api.yaml

@@ -1,4 +1,4 @@
-apiVersion: devportal.api-platform.wso2.com/v1alpha1
+apiVersion: devportal.api-platform.wso2.com/v1alpha2
 kind: RestApi
 
 metadata: