Revamp Developer Portal: add: Configure CORS how-to guide and CORS troubleshooting page

portal/how-to-guides/configure-cors.mdx

@@ -1,8 +1,170 @@
 ---
-title: "Configure CORS"
-description: "How to configure CORS at the Developer Portal application level and at the Tyk Gateway level for APIs exposed via the portal."
+title: "How to Configure CORS in Developer Portal"
+sidebarTitle: "Configure CORS"
+description: "Configure CORS for the Tyk Developer Portal application and for APIs exposed in the Live Portal, enabling consumers to test APIs from the API Playground."
+keywords: "CORS, cross-origin resource sharing, Developer Portal CORS, Gateway CORS, API Playground, PORTAL_CORS_ENABLE"
 ---
 
+Cross-origin request configuration in the Developer Portal involves two independent layers: the Portal application itself and the Tyk Gateway APIs that consumers test via the API Playground. Both layers must be configured for a fully functional cross-origin deployment.
+
+## Prerequisites
+
+- Developer Portal is deployed and accessible
+- Tyk Gateway and Dashboard are running
+- At least one [API product](/portal/api-products) is configured and published in the Portal
+- You know the public URL of your Live Portal (for example, `https://portal.example.com`)
+- You know the public URL of your Tyk Gateway (for example, `https://api.example.com`)
+
+## Configure Portal Application CORS
+
+Portal application CORS controls which external origins may call the Portal's own Admin API and Live Portal routes. It is configured via environment variables on the Portal process.
+
+<Warning>
+[PORTAL_CORS_ENABLE](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-enable) defaults to `false`. All cross-origin requests to the Portal are rejected until you set this to `true`.
+</Warning>
+
+1. **Enable CORS**
+
+   Set [PORTAL_CORS_ENABLE](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-enable) to `true` on the Portal process.
+
+   <Tabs>
+     <Tab title="Environment variable">
+       ```ini
+       PORTAL_CORS_ENABLE=true
+       ```
+     </Tab>
+     <Tab title="Config file">
+       ```json
+       {
+         "CORS": {
+           "Enable": true
+         }
+       }
+       ```
+     </Tab>
+   </Tabs>
+
+2. **Set allowed origins**
+
+   Set [PORTAL_CORS_ALLOWED_ORIGINS](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allowed-origins) to the origins permitted to make cross-origin requests to the Portal. Use the exact scheme and host of each origin, separated by commas. Wildcards are supported.
+
+   When unset, all origins are allowed by default. Specify origins explicitly to restrict access.
+
+   <Tabs>
+     <Tab title="Environment variable">
+       ```ini
+       PORTAL_CORS_ALLOWED_ORIGINS=https://admin.example.com,https://developer.example.com
+       ```
+     </Tab>
+     <Tab title="Config file">
+       ```json
+       {
+         "CORS": {
+           "AllowedOrigins": [
+             "https://admin.example.com",
+             "https://developer.example.com"
+           ]
+         }
+       }
+       ```
+     </Tab>
+   </Tabs>
+
+   <Warning>
+   Do not set [PORTAL_CORS_ALLOWED_ORIGINS](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allowed-origins) to `*` when `PORTAL_CORS_ALLOW_CREDENTIALS=true`. The CORS specification does not allow credentialed requests from wildcard origins. Specify each origin explicitly instead.
+   </Warning>
+
+3. **Set allowed headers and methods**
+
+   Set the HTTP headers and methods that cross-origin requests to the Portal may use. No headers are allowed by default. The default allowed methods are `GET` and `POST`.
+
+   <Tabs>
+     <Tab title="Environment variable">
+       ```ini
+       PORTAL_CORS_ALLOWED_HEADERS=Authorization,Content-Type,X-Requested-With
+       PORTAL_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
+       ```
+     </Tab>
+     <Tab title="Config file">
+       ```json
+       {
+         "CORS": {
+           "AllowedHeaders": ["Authorization", "Content-Type", "X-Requested-With"],
+           "AllowedMethods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
+         }
+       }
+       ```
+     </Tab>
+   </Tabs>
+
+4. **(Optional) Configure additional CORS settings**
+
+   | Config key | Default | Description |
+   |---|---|---|
+   | [CORS.MaxAge](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-max-age) | `0` | How long, in seconds, browsers may cache the preflight response. A positive value reduces preflight round trips. |
+   | [CORS.AllowCredentials](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allow-credentials) | `false` | Whether the Portal includes credentials (cookies, HTTP authentication) in CORS responses. |
+
+5. **Restart the Portal**
+
+   Restart the Portal process or pod for the environment variable changes to take effect.
+
+6. **Verify**
+
+   Open your browser developer tools and make a cross-origin request to the Portal from an allowed origin. The response headers should include `Access-Control-Allow-Origin` and the request should succeed.
+
+---
+
+## Configure Gateway CORS for APIs
+
+When a consumer tests an API using the API Playground on the Live Portal, the browser makes requests directly to the Tyk Gateway. The Portal does not proxy these requests and does not inject CORS headers. You must configure CORS on the API definition for each API exposed through the Portal.
+
+<Warning>
+**Tyk Gateway v5.8.6–v5.8.13:** A middleware ordering issue in these versions causes the allow list to run before CORS processing, returning `403 Forbidden` for OPTIONS preflight requests. 
+
+Upgrade to Gateway v5.8.14 or later to resolve this. See [Troubleshoot CORS Issues](/portal/troubleshooting/cors-issues) for diagnosis steps.
+</Warning>
+
+1. **Locate the CORS block**
+
+   In a Tyk OAS API definition, CORS configuration sits under `x-tyk-api-gateway.middleware.global.cors`.
+
+2. **Add the CORS configuration**
+
+   ```yaml expandable
+   x-tyk-api-gateway:
+     middleware:
+       global:
+         cors:
+           enabled: true
+           allowedOrigins:
+             - "https://portal.example.com"
+           allowedMethods:
+             - GET
+             - POST
+             - PUT
+             - DELETE
+             - OPTIONS
+           allowedHeaders:
+             - Origin
+             - Content-Type
+             - Authorization
+           optionsPassthrough: false
+   ```
+
+   Set `optionsPassthrough` to `false` (the default). When `false`, the Gateway intercepts OPTIONS preflight requests, responds with CORS headers, and does not forward the request to the upstream.
+
+3. **Update the API**
+
+   Update the API definition in Tyk Dashboard.
+
+4. **Verify**
+
+   Open the API Playground on your Live Portal and send a test request. The request should complete without CORS errors in the browser console.
+
 <Note>
-This page is a placeholder. Content is being written.
+If you are using a **Tyk Classic API definition**, configure CORS in Tyk Dashboard under **APIs** > **Advanced Options** > **CORS**. See the [Classic API CORS reference](/api-management/gateway-config-tyk-classic#cross-origin-resource-sharing-cors) for details.
 </Note>
+
+## Related
+
+- [Troubleshoot CORS Issues](/portal/troubleshooting/cors-issues) — diagnose and fix common CORS errors in the Developer Portal and API Playground

portal/troubleshooting/cors-issues.mdx

@@ -1,8 +1,110 @@
 ---
-title: "CORS Issues"
-description: "Troubleshoot CORS errors in the Tyk Developer Portal, including endpoint whitelisting interactions, API playground errors, and Portal vs Gateway CORS configuration."
+title: "Troubleshoot CORS Issues in Developer Portal"
+sidebarTitle: "CORS Issues"
+description: "Diagnose and fix CORS errors in the Tyk Developer Portal and API Playground."
+keywords: "CORS, troubleshooting, Access-Control-Allow-Origin, API Playground, PORTAL_CORS_ENABLE,"
 ---
 
-<Note>
-This page is a placeholder. Content is being written.
-</Note>
+Cross-origin errors in the Developer Portal arise from two independent layers: the Portal application itself and the Tyk Gateway APIs that the API Playground calls directly. Identify which layer is failing before applying a fix.
+
+<AccordionGroup>
+  <Accordion title="Access-Control-Allow-Origin header missing from Portal responses">
+    **Symptom**
+
+    Requests from your application to the Portal Admin API or Live Portal routes fail. The browser console shows:
+
+    ```
+    Access to fetch at 'https://portal.example.com/...' from origin 'https://app.example.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
+    ```
+
+    Preflight `OPTIONS` requests to the Portal return `404 Not Found` or `405 Method Not Allowed`.
+
+    **Cause**
+
+    [PORTAL_CORS_ENABLE](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-enable) is `false` (the default). The Portal's CORS middleware is disabled, so no `Access-Control-Allow-Origin` header is added to any response and `OPTIONS` preflight requests fall through to the router with no matching handler.
+
+    **Fix**
+
+    Enable Portal CORS and set your allowed origins. See [Configure Portal Application CORS](/portal/how-to-guides/configure-cors#configure-portal-application-cors).
+  </Accordion>
+
+  <Accordion title="API Playground requests fail with 401 Unauthorized or missing CORS headers">
+    **Symptom**
+
+    Test requests in the API Playground fail. The browser console shows one of:
+
+    - `401 Unauthorized` on the `OPTIONS` preflight request
+    - `Access to fetch at 'https://api.example.com/...' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.`
+
+    **Cause**
+
+    The API definition in Tyk Gateway has CORS misconfigured:
+
+    - **CORS disabled entirely**: The Gateway routes the `OPTIONS` preflight through the authentication middleware. Because preflight requests carry no `Authorization` header, the Gateway rejects them with `401 Unauthorized`.
+    - **CORS enabled but Portal origin not in the allowed list**: The Gateway intercepts the preflight and returns `200 OK`, but omits the `Access-Control-Allow-Origin` header because the Portal's origin does not match `allowed_origins`. The browser treats this as a CORS failure.
+
+    **Fix**
+
+    Configure CORS on the API definition and add your Portal URL to the allowed origins. See [Configure Gateway CORS for APIs](/portal/how-to-guides/configure-cors#configure-gateway-cors-for-apis).
+  </Accordion>
+
+  <Accordion title="403 Forbidden on OPTIONS preflight in Gateway v5.8.6–v5.8.13">
+    **Symptom**
+
+    API Playground requests fail on Gateway versions v5.8.6 through v5.8.13, even when CORS is correctly configured and the Portal origin is in `allowed_origins`. The browser console shows:
+
+    ```
+    TypeError: Failed to fetch
+    ```
+
+    The `OPTIONS` preflight returns `403 Forbidden` with one of the following response bodies:
+
+    ```json
+    {"error": "Requested endpoint is forbidden"}
+    ```
+
+    ```json
+    {"error": "Access to this API has been disallowed"}
+    ```
+
+    **Cause**
+
+    A middleware ordering regression in Gateway versions v5.8.6–v5.8.13 caused the allow-list middleware (`VersionCheck`) to run before the CORS middleware. The allow-list evaluates the `OPTIONS` method against endpoint rules and returns `403 Forbidden` before the CORS middleware can intercept and handle the preflight.
+
+    **Fix**
+
+    Upgrade Tyk Gateway to v5.8.14 or later, where the middleware ordering is corrected.
+  </Accordion>
+
+  <Accordion title="CORS error: wildcard origin rejected when credentials are enabled">
+    **Symptom**
+
+    Credentialed cross-origin requests to the Portal fail. The browser console shows:
+
+    ```
+    The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*' when the request's credentials mode is 'include'.
+    ```
+
+    **Cause**
+
+    [PORTAL_CORS_ALLOW_CREDENTIALS](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allow-credentials)=true is set alongside [PORTAL_CORS_ALLOWED_ORIGINS](/product-stack/tyk-enterprise-developer-portal/deploy/configuration#portal-cors-allowed-origins)=*. The Portal's CORS library (`rs/cors`) does not reject this combination at startup — it returns both `Access-Control-Allow-Origin: *` and `Access-Control-Allow-Credentials: true` in the response. The CORS specification forbids this combination, so the browser rejects the response.
+
+    **Fix**
+
+    Replace the wildcard with explicit allowed origins:
+
+    ```ini
+    PORTAL_CORS_ALLOWED_ORIGINS=https://admin.example.com,https://app.example.com
+    PORTAL_CORS_ALLOW_CREDENTIALS=true
+    ```
+
+    See [Configure Portal Application CORS](/portal/how-to-guides/configure-cors#configure-portal-application-cors).
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## Related
+
+- [Configure CORS](/portal/how-to-guides/configure-cors) — set up Portal application CORS and Gateway API CORS
+- [Portal configuration reference](/product-stack/tyk-enterprise-developer-portal/deploy/configuration) — full list of Portal environment variables

product-stack/tyk-enterprise-developer-portal/deploy/configuration.mdx

@@ -522,7 +522,7 @@ In other words, any cross-origin request will be denied. When enabled, the below
 **Config file:** CORS.AllowedOrigins <br/>
 **Type:** `[string]` <br/>
 **Description**: A list of origin domains to allow access from. Wildcards are also supported, e.g. [`*.foo.com`] will allow access from any domain that ends with *.foo.com*.
-By default, no origins are allowed. To apply this setting, an array of the allowed origins.
+When unset, all origins are allowed by default. Specify origins explicitly to restrict access.
 
 To configure using a configuration file:
 ```json