Cookie Auth

Docula supports cookie-based authentication that displays a Log In or Log Out button in the site header. When a JWT cookie is detected in the browser, the button switches to "Log Out"; otherwise it shows "Log In".

This is useful for documentation sites that are gated behind an OAuth provider, such as docs.hyphen.ai.

Table of Contents

• Configuration
  • Options
• How It Works
  • Logout Behavior
• User Display Name
• API Reference Integration

Configuration

Add the cookieAuth option to your docula.config.ts:

import type { DoculaOptions } from 'docula';

export const options: Partial<DoculaOptions> = {
  siteTitle: 'My Project',
  cookieAuth: {
    loginUrl: '/login',
    cookieName: 'auth_token',
  },
};

Options

How It Works

1. When cookieAuth is configured, a Log In link and a hidden Log Out button are rendered in the site header (both desktop and mobile).
2. On page load, client-side JavaScript checks whether the configured cookie exists.
3. If the cookie is present, the "Log In" link is hidden and the "Log Out" button is shown.
4. If the cookie is not present, the "Log In" link is shown and the "Log Out" button is hidden.

Logout Behavior

With logoutUrl: Clicking "Log Out" redirects to the specified URL. Use this when your auth provider has a dedicated logout endpoint.

cookieAuth: {
  loginUrl: '/login',
  cookieName: 'session',
  logoutUrl: '/api/auth/logout',
},

Without logoutUrl: Clicking "Log Out" clears the cookie and reloads the page.

cookieAuth: {
  loginUrl: '/login',
  cookieName: 'session',
},

User Display Name

When a user is logged in, Docula extracts a display name from the JWT cookie and shows it in the site header. The name is resolved from the token's claims in this order:

1. name
2. preferred_username
3. email

If none of these claims are present, no name is displayed.

API Reference Integration

When cookieAuth is configured and your OpenAPI spec defines an API Key security scheme with "in": "cookie", the API Reference page shows a login status indicator in the authorization panel — green when logged in, amber when not. Requests made via the "Try It" panel automatically include the cookie, so no manual token entry is needed.