Copy page

Authentication

OAuth Security Schemes

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.

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 and API identity 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:

zudoku.config.ts
const config = {
  authentication: {
    type: "auth0",
    domain: "yourdomain.us.auth0.com",
    clientId: "<your-auth0-client-id>",
  },
};

Or using any OpenID Connect provider:

zudoku.config.ts
const config = {
  authentication: {
    type: "openid",
    clientId: "<your-client-id>",
    issuer: "https://your-idp.example.com",
  },
};

See Authentication 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 that bridges the two:

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:

zudoku.config.ts
const config = {
  apis: {
    type: "file",
    input: "./openapi.json",
    path: "/api",
    options: {
      disableSecurity: true,
    },
  },
};