zuplo 6.68.10 → 6.68.16

package/docs/articles/troubleshooting-slow-responses.mdx

@@ -234,6 +234,76 @@ performance. Use it to:
 - Spot error rate spikes that may correlate with latency issues
 - Track request volume trends that may indicate capacity-related slowness
 
+### OpenTelemetry Tracing
+
+For the most detailed view of where time is spent in your request pipeline,
+enable [OpenTelemetry tracing](./opentelemetry.mdx). The OpenTelemetry plugin
+automatically instruments your API and provides span-level timing for each stage
+of the request lifecycle — including inbound policies, the handler, outbound
+policies, and any subrequests made via `fetch` in custom code.
+
+<EnterpriseFeature name="OpenTelemetry" />
+
+With tracing enabled, you can see exactly how long each policy and handler takes
+to execute, making it straightforward to identify which component is adding
+latency. The plugin also supports W3C trace propagation, so you can follow a
+request all the way from the client through Zuplo to your backend.
+
+To get started, add the `OpenTelemetryPlugin` in your `zuplo.runtime.ts` file
+and configure it to export trace data to any OpenTelemetry-compatible service
+such as [Honeycomb](https://honeycomb.io), [Dynatrace](https://dynatrace.com),
+[Jaeger](https://www.jaegertracing.io/), or an
+[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/):
+
+```ts title="zuplo.runtime.ts"
+import { OpenTelemetryPlugin } from "@zuplo/otel";
+import { RuntimeExtensions, environment } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new OpenTelemetryPlugin({
+      exporter: {
+        url: "https://otel-collector.example.com/v1/traces",
+        headers: {
+          "api-key": environment.OTEL_API_KEY,
+        },
+      },
+      service: {
+        name: "my-api",
+        version: "1.0.0",
+      },
+    }),
+  );
+}
+```
+
+You can also add custom spans within your policies to trace specific operations:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+import { trace } from "@opentelemetry/api";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const tracer = trace.getTracer("my-tracer");
+  return tracer.startActiveSpan("my-custom-operation", async (span) => {
+    span.setAttribute("endpoint", request.url);
+
+    try {
+      // ... policy logic with external calls ...
+      return request;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+For the full configuration reference, including sampling, post-processing, and
+logging, see the [OpenTelemetry documentation](./opentelemetry.mdx).
+
 ### Logging Integrations
 
 For deeper analysis, configure one of Zuplo's
@@ -290,6 +360,8 @@ back-and-forth diagnostic questions.
 
 ## Related Resources
 
+- [OpenTelemetry](./opentelemetry.mdx) — Distributed tracing and logging for
+  detailed request lifecycle visibility
 - [Performance Testing Your API Gateway](./performance-testing.mdx) — How to
   benchmark and compare gateway performance accurately
 - [Proactive Monitoring](./monitoring-your-gateway.mdx) — Setting up health

package/docs/dev-portal/zudoku/configuration/api-reference.md

@@ -206,6 +206,7 @@ const config = {
       ],
       disablePlayground: false, // Disable the interactive API playground
       disableSidecar: false, // Disable the sidecar completely
+      disableSecurity: true, // Disable security scheme display and playground auth (default)
       showVersionSelect: "if-available", // Control version selector visibility
       expandAllTags: true, // Control initial expanded state of tag categories
       showInfoPage: true, // Show API information page as the index route
@@ -224,6 +225,9 @@ Available options:
   identifier) and `label` (display name)
 - `disablePlayground`: Disable the interactive API playground globally
 - `disableSidecar`: Disable the sidecar panel completely
+- `disableSecurity`: Disable OpenAPI security scheme display (auth badges on operations, security
+  schemes section on the info page, and the Authorize dialog in the playground). Disabled by default
+  (`true`). Set to `false` to enable security scheme support
 - `showVersionSelect`: Control version selector visibility
   - `"if-available"`: Show version selector only when multiple versions exist (default)
   - `"always"`: Always show version selector (disabled if only one version)
@@ -251,6 +255,7 @@ const config = {
       examplesLanguage: "shell", // Default language for code examples
       disablePlayground: false, // Disable the interactive API playground
       disableSidecar: false, // Disable the sidecar completely
+      disableSecurity: true, // Disable security scheme display and playground auth (default)
       showVersionSelect: "if-available", // Control version selector visibility
       expandAllTags: false, // Control initial expanded state of tag categories
       showInfoPage: true, // Show API information page as the index route

package/docs/dev-portal/zudoku/configuration/authentication-auth0.md

@@ -160,8 +160,8 @@ When the prompt parameter is omitted (empty string), Auth0 will:
 
 2. **CORS Errors**: Add your site's domain to the Allowed Web Origins in Auth0.
 
-3. **Authentication Loop**: Check that your Auth0 domain includes the protocol (`https://`) but no
-   trailing slash.
+3. **Authentication Loop**: Check that your Auth0 domain is a plain hostname only (e.g.,
+   `your-domain.us.auth0.com`) without a protocol prefix (`https://`) or trailing slash.
 
 4. **Token Validation Errors**: Ensure the audience in your Dev Portal configuration matches the
    identifier of the Auth0 API you created.

package/docs/dev-portal/zudoku/configuration/authentication-azure-ad.md

@@ -44,9 +44,8 @@ to integrate Azure AD with your Dev Portal documentation site.
      - Production: `https://your-site.com/oauth/callback`
      - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
      - Local Development: `http://localhost:3000/oauth/callback`
-   - Under **Implicit grant and hybrid flows**:
-     - Enable **ID tokens**
-     - Enable **Access tokens**
+   - **Implicit grant and hybrid flows** should remain **disabled** — Dev Portal uses the more secure
+     Authorization Code flow with PKCE
    - Configure **Supported account types** if needed
    - Save your changes
 
@@ -82,14 +81,6 @@ to integrate Azure AD with your Dev Portal documentation site.
    };
    ```
 
-5. **Install Azure AD Dependencies**
-
-   Add `@azure/msal-browser` to your project dependencies:
-
-   ```bash
-   npm install @azure/msal-browser
-   ```
-
 </Stepper>
 
 ## Configuration Options
@@ -217,8 +208,8 @@ Azure AD provides rich user profile data through OpenID Connect:
 5. **Token Validation Errors**: Ensure your issuer URL is correct and includes the `/v2.0` endpoint
    for the Microsoft identity platform.
 
-6. **Authentication Not Working**: Make sure you have installed `@azure/msal-browser` to your
-   project.
+6. **Authentication Not Working**: Verify your issuer URL and client ID are correct, and that your
+   app registration is configured as a Single-page application (SPA) with the correct redirect URIs.
 
 ## Security Best Practices
 

package/docs/dev-portal/zudoku/configuration/authentication-clerk.md

@@ -68,23 +68,23 @@ that provides 10,000 monthly active users.
 
 4. **Configure Redirect URLs (Optional)**
 
-   If you need custom redirect behavior, configure the allowed redirect URLs in Clerk:
-   - Go to **Paths** in your Clerk dashboard
-   - Add your production, preview, and local development URLs to the allowed redirect URLs
-   - Common patterns:
-     - Production: `https://your-site.com/oauth/callback`
-     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-     - Local Development: `http://localhost:3000/oauth/callback`
+   If you need custom redirect behavior after sign-in or sign-up, you can configure this in your
+   Dev Portal config:
 
-5. **Install Clerk Dependencies**
-
-   Add `@clerk/clerk-js` to your project dependencies:
-
-   ```bash
-   npm install @clerk/clerk-js
+   ```typescript
+   authentication: {
+     type: "clerk",
+     clerkPubKey: "<your-clerk-publishable-key>",
+     jwtTemplateName: "<your-clerk-jwt-template-name>",
+     redirectToAfterSignIn: "/docs",
+     redirectToAfterSignUp: "/getting-started",
+     redirectToAfterSignOut: "/",
+   },
    ```
 
-   </Stepper>
+   You should also ensure your site's domain is added as an allowed origin in the Clerk dashboard.
+
+</Stepper>
 
 ## Troubleshooting
 
@@ -99,8 +99,9 @@ that provides 10,000 monthly active users.
 3. **Redirect Issues**: Check that your domain is added to the allowed redirect URLs in Clerk if
    using custom redirects.
 
-4. **ReferenceError: can't access lexical declaration 'xxx' before initialization**: Make sure you
-   have installed Clerk to your project.
+4. **ReferenceError: can't access lexical declaration 'xxx' before initialization**: This can happen
+   if the Clerk CDN script fails to load. Check your network connectivity and ensure your
+   publishable key is valid.
 
 ## Next Steps
 

package/docs/dev-portal/zudoku/configuration/authentication-firebase.md

@@ -49,7 +49,7 @@ export default {
     measurementId: "G-12W6TTNR75",
     // Optional: specify which providers to show in the sign-in UI
     // Available providers: "google", "github", "facebook", "twitter",
-    // "microsoft", "apple", "yahoo", "password", "phone"
+    // "microsoft", "apple", "yahoo", "password", "emailLink"
     // If not specified, all enabled providers in Firebase will be available
     providers: ["google", "github", "password"],
     // Optional: configure redirect URLs after authentication

package/docs/dev-portal/zudoku/configuration/authentication-supabase.md

@@ -2,79 +2,163 @@
 title: Supabase Setup
 sidebar_label: Supabase
 description:
-  Learn how to set up Supabase authentication for Zudoku, leveraging Supabase's built-in auth
-  providers for secure documentation access.
+  Learn how to set up Supabase authentication for Dev Portal using email and password or OAuth providers
+  for secure documentation access.
 ---
 
 Supabase is an open-source Firebase alternative that provides authentication, database, and storage
 services. This guide shows you how to integrate Supabase authentication with your Dev Portal documentation site.
 
+You can use **email and password** (Supabase signs users in with an email address and password),
+**OAuth providers** (GitHub, Google, and so on), or both. Follow the section that matches how you
+want users to sign in.
+
 ## Prerequisites
 
 You'll need a Supabase project. If you don't have one,
 [create a free Supabase project](https://supabase.com/dashboard) to get started.
 
-## Setup Steps
+## Setup Steps for Email and Password
+
+Use this path when users should sign up and sign in with an email address and password managed by
+Supabase.
 
 <Stepper>
 
-1. **Configure Authentication Provider**
+<a id="configure-email-sign-in"></a>
+
+1. **Enable email authentication in Supabase**
 
    In your [Supabase Dashboard](https://supabase.com/dashboard):
-   - Navigate to **Authentication** → **Providers**
-   - Enable your preferred authentication provider (GitHub, Google, Azure, etc.)
-   - Configure the provider settings:
-     - **Redirect URL**: `https://your-project.supabase.co/auth/v1/callback`
-     - Copy any required credentials (Client ID, Client Secret) from the provider
+   - Select the project you are going to use
+   - Go to **Authentication** → **Configuration** → **Sign In / Providers**
+   - Under **Email**, ensure **Email sign-in** is enabled
+   - Decide whether new users must confirm their email before signing in (see **Confirm email** in
+     the same area). If confirmation is required, Supabase sends a link that returns users to your
+     Dev Portal portal (see [Authentication Routes](#authentication-routes))
 
-2. **Get Your Project Credentials**
+2. **Copy your Supabase URL and publishable key**
 
    From your Supabase project dashboard:
-   - Go to **Settings** → **Data API**
-   - Copy your **Project URL** (looks like `https://your-project.supabase.co`)
-   - Go to **Settings** → **API Keys**
-   - Copy your **anon public** API key
+   - Go to **Project Settings** → **Integrations** → **Data API**
+   - Copy your **API URL** (looks like `https://your-project-id.supabase.co`)
+   - Go to **Configuration** → **API Keys**
+   - Copy your **publishable** key (looks like `sb_publishable_...`)
 
 3. **Configure Zudoku**
 
-   Add the Supabase configuration to your [Dev Portal configuration file](./overview.md):
+   Add the following to your [Dev Portal configuration file](./overview.md). Omit `providers` or set it
+   to an empty array when you are only using email and password:
 
    ```ts title="zudoku.config.ts"
    export default {
      // ... other configuration
      authentication: {
        type: "supabase",
-       providers: ["github"], // one or more providers
+       providers: [],
        supabaseUrl: "https://your-project.supabase.co",
-       supabaseKey: "<your-anon-public-key>",
+       supabaseKey: "<your-publishable-key>",
      },
      // ... other configuration
    };
    ```
 
-   You can configure multiple providers:
+4. **Install Supabase dependencies**
+
+   Install the packages Dev Portal expects for the Supabase client and auth UI:
+
+   ```bash
+   npm install @supabase/supabase-js
+   ```
+
+5. **Configure redirect URLs in Supabase**
+
+   Supabase only redirects to URLs you allow. This matters for **email confirmation**, **password
+   reset**, and **magic links** (if you use them elsewhere).
+
+   From your Supabase project dashboard, go to **Authentication** → **Configuration** → **URL
+   Configuration** and set:
+   - **Site URL**: Your primary deployed URL (for example `https://docs.example.com`), or
+     `http://localhost:3000` while developing locally.
+   - **Redirect URLs**: Include every origin where your docs run, with a path wildcard so deep links
+     work, for example:
+     - Production: `https://docs.example.com/**`
+     - Local dev: `http://localhost:3000/**`
+
+   Use the same origins and [base path](./overview.md) you use in the browser.
+
+</Stepper>
+
+## Setup Steps for Authentication Providers
+
+Use this path when users should sign in with OAuth (for example GitHub or Google). Set
+`onlyThirdPartyProviders: true` if you do not want email and password fields on the sign-in and
+sign-up pages.
+
+<Stepper>
+
+<a id="configure-authentication-provider"></a>
+
+1. **Configure Authentication Provider**
+
+   In your [Supabase Dashboard](https://supabase.com/dashboard):
+   - Select the Supabase project you are going to use
+   - Navigate to **Authentication** → **Configuration** → **Sign In / Providers**
+   - Enable your preferred authentication provider (GitHub, Google, Azure, etc.)
+   - Follow the Supabase configuration documentation for that provider
+
+2. **Copy your Supabase URL and publishable key**
+
+   From your Supabase project dashboard:
+   - Go to **Project Settings** → **Integrations** → **Data API**
+   - Copy your **API URL** (looks like `https://your-project-id.supabase.co`)
+   - Go to **Configuration** → **API Keys**
+   - Copy your **publishable** key (looks like `sb_publishable_...`)
+
+3. **Configure Zudoku**
+
+   Add the following to your [Dev Portal configuration file](./overview.md), using the API URL and
+   publishable key from the previous step. Include every OAuth provider you enabled in Supabase in
+   the `providers` array (see [Supported Providers](#supported-providers)):
 
    ```ts title="zudoku.config.ts"
    export default {
      // ... other configuration
      authentication: {
        type: "supabase",
-       providers: ["github", "google", "azure"],
+       providers: ["github"], // one or more providers — required for OAuth sign-in
        supabaseUrl: "https://your-project.supabase.co",
-       supabaseKey: "<your-anon-public-key>",
+       supabaseKey: "<your-publishable-key>",
      },
      // ... other configuration
    };
    ```
 
-4. **Install Supabase Dependencies**
+4. **Install Supabase dependencies**
 
-   Add `@supabase/supabase-js` to your project dependencies:
+   Install the Supabase client and auth UI packages your Dev Portal project expects:
 
    ```bash
-   npm install @supabase/supabase-js @supabase/auth-ui-shared @supabase/auth-ui-react
+   npm install @supabase/supabase-js
    ```
 
+5. **Configure redirect URLs in Supabase**
+
+   Supabase only redirects back to URLs you allow. Add every environment where users sign in:
+
+   From your Supabase project dashboard, go to **Authentication** → **Configuration** → **URL
+   Configuration** and update:
+   - **Site URL**: Your primary deployed URL (for example `https://docs.example.com`), or
+     `http://localhost:3000` while developing locally.
+   - **Redirect URLs**: Include your Dev Portal site origin(s), for example:
+     - Production: `https://docs.example.com/**`
+     - Local dev: `http://localhost:3000/**`
+     - Preview deployments: a pattern your host uses, such as `https://*.vercel.app/**`, if
+       applicable.
+
+   Use the same paths you use in the browser (including any [base path](./overview.md) prefix). If
+   OAuth redirects fail or send users to the wrong host, this section is usually the cause.
+
 </Stepper>
 
 ## Supported Providers
@@ -103,13 +187,43 @@ array:
 - `zoom` - Zoom
 - `fly` - Fly.io
 
-:::info
+## Email and Password with OAuth
+
+To offer **both** email/password and OAuth buttons, leave `onlyThirdPartyProviders` unset (or set it
+to `false`) and list your OAuth providers in `providers`. Complete
+[Enable email authentication in Supabase](#configure-email-sign-in) and
+[Configure Authentication Provider](#configure-authentication-provider) as needed, then use a config
+similar to:
+
+```ts title="zudoku.config.ts"
+export default {
+  authentication: {
+    type: "supabase",
+    providers: ["github", "google"],
+    supabaseUrl: "https://your-project.supabase.co",
+    supabaseKey: "<your-publishable-key>",
+  },
+};
+```
+
+## Configuring Multiple Providers
 
-Email/password authentication does not need to be specified as a provider because it is enabled by
-default in Supabase. To disable email/password authentication and only use OAuth providers, set
-`onlyThirdPartyProviders: true` in your configuration.
+Complete [Configure Authentication Provider](#configure-authentication-provider) in the Supabase
+dashboard for each provider you need, then list them in the `providers` array:
 
-:::
+```ts title="zudoku.config.ts"
+export default {
+  // ... other configuration
+  authentication: {
+    type: "supabase",
+    onlyThirdPartyProviders: true,
+    providers: ["github", "google", "azure"],
+    supabaseUrl: "https://your-project.supabase.co",
+    supabaseKey: "<your-publishable-key>",
+  },
+  // ... other configuration
+};
+```
 
 ## Configuration Options
 
@@ -119,18 +233,18 @@ All available configuration options for Supabase authentication:
 authentication: {
   type: "supabase",
 
-  // Provider configuration (required)
-  // Array of one or more OAuth providers to enable
+  // OAuth providers to show as buttons (optional for email/password-only; required for OAuth)
+  // See Supported Providers — values must match Supabase provider IDs
   providers: ["google", "github"],
 
   // Supabase credentials (required)
   supabaseUrl: "https://your-project.supabase.co",
-  supabaseKey: "<your-anon-public-key>",
+  supabaseKey: "<your-publishable-key>",
 
   // Optional: Custom base path for auth routes (default: "/")
   basePath: "/docs",
 
-  // Optional: Disable email/password authentication, only use OAuth providers
+  // Optional: When true, sign-in and sign-up pages show only OAuth buttons (no email/password)
   onlyThirdPartyProviders: true,
 
   // Optional: Redirect URLs after authentication events
@@ -144,9 +258,9 @@ authentication: {
 
 The Supabase authentication provider automatically creates the following routes:
 
-- `/signin` - Sign in page with configured providers
-- `/signup` - Sign up page with configured providers
-- `/signout` - Sign out endpoint
+- `/signin` - Sign in (email and password when enabled, plus any configured OAuth providers)
+- `/signup` - Sign up (same as sign-in)
+- `/signout` - Sign out
 
 If you configure a custom `basePath`, these routes will be prefixed with that path (e.g.,
 `/docs/signin`).
@@ -201,23 +315,30 @@ CREATE TRIGGER on_auth_user_created
 
 ### Common Issues
 
-1. **"At least one provider must be provided" Error**: You must configure the `providers` option in
-   your authentication configuration with at least one authentication provider in the array.
+1. **OAuth sign-in shows no provider buttons**: For OAuth-only setups, add at least one provider ID
+   to the `providers` array that matches a provider you enabled in Supabase. For **email and
+   password only**, you can use `providers: []` — see
+   [Setup Steps for Email and Password](#setup-steps-for-email-and-password).
+
+2. **Email/password fields when you want OAuth only**: Set `onlyThirdPartyProviders: true` so the
+   sign-in and sign-up screens show only OAuth buttons. Leave this unset (or `false`) when you want
+   email and password fields — see
+   [Setup Steps for Email and Password](#setup-steps-for-email-and-password).
 
-2. **Invalid API Key**: Ensure you're using the `anon public` key, not the `service_role` key from
-   your Supabase project settings.
+3. **Invalid API key**: Use the **publishable** client key in `supabaseKey`, not the **secret**
+   (service role) key.
 
-3. **Provider Not Working**: Verify the provider is enabled in your Supabase dashboard and properly
+4. **Provider Not Working**: Verify the provider is enabled in your Supabase dashboard and properly
    configured with the correct redirect URLs.
 
-4. **Redirect URLs**: For local development, update your redirect URLs in both Supabase and the
+5. **Redirect URLs**: For local development, update your redirect URLs in both Supabase and the
    OAuth provider to include `http://localhost:3000`.
 
-5. **CORS Errors**: Check that your site's domain is properly configured in Supabase's allowed URLs
+6. **CORS Errors**: Check that your site's domain is properly configured in Supabase's allowed URLs
    under **Authentication** → **URL Configuration**.
 
-6. **Authentication Not Working**: Make sure you have installed all required dependencies:
-   `@supabase/supabase-js`, `@supabase/auth-ui-react`, and `@supabase/auth-ui-shared`.
+7. **Authentication Not Working**: Make sure you have installed `@supabase/supabase-js` in your
+   project dependencies.
 
 ## Next Steps
 

package/docs/dev-portal/zudoku/configuration/authentication.md

@@ -117,7 +117,7 @@ the Firebase console under Project Settings.
 ```
 
 The `providers` option configures which sign-in methods are available. Supported providers include:
-`google`, `facebook`, `twitter`, `github`, `microsoft`, `apple`, `yahoo`, `password`, `phone`, and
+`google`, `facebook`, `twitter`, `github`, `microsoft`, `apple`, `yahoo`, `password`, and
 `emailLink`.
 
 For detailed setup instructions, see the [Firebase setup guide](./authentication-firebase.md).
@@ -125,14 +125,14 @@ For detailed setup instructions, see the [Firebase setup guide](./authentication
 ### Supabase
 
 To use Supabase as your authentication provider, supply your project's URL, API key, and the OAuth
-provider to use.
+providers to use.
 
 ```typescript title="zudoku.config.ts"
 {
   // ...
   authentication: {
     type: "supabase",
-    provider: "github",
+    providers: ["github"],
     supabaseUrl: "https://your-project.supabase.co",
     supabaseKey: "<your-supabase-key>",
     redirectToAfterSignUp: "/",
@@ -143,10 +143,10 @@ provider to use.
 }
 ```
 
-The `provider` option can be any of Supabase Auth's supported providers, such as `apple`, `azure`,
-`bitbucket`, `discord`, `facebook`, `figma`, `github`, `gitlab`, `google`, `kakao`, `keycloak`,
-`linkedin`, `linkedin_oidc`, `notion`, `slack`, `slack_oidc`, `spotify`, `twitch`, `twitter`,
-`workos`, `zoom`, or `fly`.
+The `providers` option accepts an array of Supabase Auth's supported providers, such as `apple`,
+`azure`, `bitbucket`, `discord`, `facebook`, `figma`, `github`, `gitlab`, `google`, `kakao`,
+`keycloak`, `linkedin`, `linkedin_oidc`, `notion`, `slack`, `slack_oidc`, `spotify`, `twitch`,
+`twitter`, `workos`, `zoom`, or `fly`.
 
 ### Azure B2C
 

package/docs/dev-portal/zudoku/configuration/oauth-security-schemes.md

@@ -0,0 +1,122 @@
+---
+title: OAuth Security Schemes
+sidebar_icon: shield
+---
+
+If your OpenAPI specification defines OAuth2 or OpenID Connect security schemes, Dev Portal will display
+them as informational badges on your API operations. However, interactive OAuth flows (such as
+Authorization Code or Client Credentials) are **not active by default** in the playground. To enable
+OAuth-based authentication for API requests, you need to configure a Dev Portal [authentication provider](./authentication.md).
+
+## Why Dev Portal Uses Its Own Authentication System
+
+OpenAPI `securitySchemes` describe _what_ authentication an API requires, but they don't include the
+runtime configuration needed to actually perform an OAuth flow — such as the client ID, client
+secret, redirect URI, or provider-specific settings.
+
+Rather than attempting to derive a working OAuth flow from incomplete spec metadata, Dev Portal gives
+you full control through its authentication plugin system. This approach:
+
+- Works reliably across OAuth providers (Auth0, Azure B2C, Okta, Keycloak, etc.) without
+  provider-specific workarounds
+- Avoids exposing client secrets in the browser
+- Handles token refresh, session management, and logout correctly
+- Integrates with Zudoku's [protected routes](./protected-routes.md) and
+  [API identity](../concepts/auth-provider-api-identities.md) system
+
+## Setting Up OAuth for the Playground
+
+To enable OAuth-based authentication in the API playground, follow these two steps:
+
+### 1. Configure an Authentication Provider
+
+Add an `authentication` block to your `zudoku.config.ts`. This handles the OAuth flow (redirects,
+token exchange, session management) for your documentation portal.
+
+For example, using Auth0:
+
+```ts title=zudoku.config.ts
+const config = {
+  authentication: {
+    type: "auth0",
+    domain: "yourdomain.us.auth0.com",
+    clientId: "<your-auth0-client-id>",
+  },
+};
+```
+
+Or using any OpenID Connect provider:
+
+```ts title=zudoku.config.ts
+const config = {
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "https://your-idp.example.com",
+  },
+};
+```
+
+See [Authentication](./authentication.md) for the full list of supported providers.
+
+### 2. Create an API Identity Plugin
+
+The authentication provider signs users into the portal. To use their token for API requests in the
+playground, create an [API Identity plugin](../concepts/auth-provider-api-identities.md) that
+bridges the two:
+
+```ts title=zudoku.config.ts
+import { createApiIdentityPlugin } from "zudoku/plugins";
+
+const config = {
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "https://your-idp.example.com",
+  },
+  plugins: [
+    createApiIdentityPlugin({
+      getIdentities: async (context) => [
+        {
+          id: "oauth-token",
+          label: "OAuth Token",
+          authorizeRequest: (request) => {
+            return context.authentication?.signRequest(request);
+          },
+        },
+      ],
+    }),
+  ],
+};
+```
+
+Once configured, users can sign in to your documentation portal and their OAuth token will be
+automatically attached to API requests made from the playground.
+
+## What About Non-OAuth Security Schemes?
+
+Simple security schemes like API keys and HTTP bearer tokens defined in your OpenAPI spec work in
+the playground without any additional Dev Portal configuration. Users can enter their credentials
+directly in the playground's Authorize dialog.
+
+OAuth2 and OpenID Connect schemes are the exception — they require the authentication provider
+configuration described above because performing OAuth flows requires runtime configuration that
+goes beyond what OpenAPI specifies.
+
+## Disabling Security Scheme Display
+
+If you don't want security scheme information displayed at all (badges on operations, the security
+schemes section on the info page, and the Authorize dialog), you can disable it:
+
+```ts title=zudoku.config.ts
+const config = {
+  apis: {
+    type: "file",
+    input: "./openapi.json",
+    path: "/api",
+    options: {
+      disableSecurity: true,
+    },
+  },
+};
+```

package/docs/dev-portal/zudoku/configuration/site.md

@@ -87,6 +87,44 @@ Set the text direction for your site. This is useful for right-to-left languages
 We allow you to fully customize all colors, borders, etc - read more about it in
 [Colors & Themes](/dev-portal/zudoku/customization/colors-theme)
 
+#### Custom 404 Page
+
+Replace the default "Page not found" page with your own component using the `notFoundPage` option:
+
+```tsx title=zudoku.config.tsx
+import { NotFound } from "./src/NotFound";
+
+const config = {
+  site: {
+    notFoundPage: <NotFound />,
+  },
+};
+```
+
+Your component will be rendered whenever a user navigates to a route that doesn't exist. This works
+in both development and production builds.
+
+Here's an example of a custom 404 component:
+
+```tsx title=src/NotFound.tsx
+import { Button, Link } from "zudoku/components";
+
+export const NotFound = () => (
+  <section className="flex items-center justify-center py-20">
+    <div className="text-center max-w-lg mx-auto">
+      <p className="text-6xl font-extrabold text-primary mb-4">404</p>
+      <h1 className="text-3xl font-bold mb-4">Page not found</h1>
+      <p className="text-muted-foreground mb-8">
+        The page you're looking for doesn't exist or has been moved.
+      </p>
+      <Button asChild>
+        <Link to="/">Go back home</Link>
+      </Button>
+    </div>
+  </section>
+);
+```
+
 ## Layout
 
 ### Banner
@@ -126,6 +164,7 @@ Here's a comprehensive example showing all available page configuration options:
       alt: "Company Logo",
       width: "100px",
     },
+    notFoundPage: <NotFound />,
     banner: {
       message: "Welcome to our documentation!",
       color: "info",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.68.10",
+  "version": "6.68.16",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.68.10",
-    "@zuplo/core": "6.68.10",
-    "@zuplo/runtime": "6.68.10",
+    "@zuplo/cli": "6.68.16",
+    "@zuplo/core": "6.68.16",
+    "@zuplo/runtime": "6.68.16",
     "@zuplo/test": "1.4.0"
   }
 }