Authentication

<OpenApiEndpoint> auto-detects the auth scheme from the spec's securitySchemes and renders an appropriate input.

Supported schemes

Scheme	Input	Header injected
bearer	Token (password)	Authorization: Bearer <token>
basic	username:password	Authorization: Basic <value>
apikey	Key (password)	Custom header (from spec or X-API-Key)
oauth2	Token paste	Authorization: Bearer <token>

How it works

1. The parser reads components.securitySchemes from your spec
2. Each operation's security array references a scheme by name
3. <OpenApiEndpoint> resolves the scheme type and renders <AuthControls>
4. The user enters a credential, stored in sessionStorage under vod:auth:{specName}
5. The credential auto-injects into:
   • SDK snippets (curl, fetch, Python): visible and copy-pasteable
   • Try-It panel: via the before-send hook

Session storage

Credentials persist across SPA navigation within the same tab. They clear when:

• The user clicks Clear credentials
• The browser tab is closed
• sessionStorage is cleared

Each spec has its own credential store; setting auth on one API doesn't affect another.

Override per endpoint

Force a specific scheme:

<OpenApiEndpoint id="api.users.list" auth="bearer" />

Disable auth entirely:

<OpenApiEndpoint id="api.public.health" auth="none" />

The credential input lives inside the Try-It panel, so show must include try for it to appear (alongside auth). With try omitted there's no place to enter a credential. In the columns layout the aside also shows a read-only "{scheme} required" label whenever auth is in show.

API key header name

For apiKey schemes, the header name is read from the spec:

components:
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Custom-Key
      in: header

Override per endpoint:

<OpenApiEndpoint id="api.users.list" api-key-header-name="X-Override" />

Key location (in)

The scheme's in field decides where the key goes:

• in: header (default): the key is sent as the configured header in both snippets and Try-It.
• in: query: the key is appended as a query parameter (?api_key=...) in both snippets and Try-It.
• in: cookie: the browser cannot set a Cookie header from fetch, so the Try-It panel sends the request without the credential and shows a warning. Snippets fall back to emitting the key as a request header, since a server-side client can send it.

OAuth2

For oauth2 schemes, the plugin renders:

• Authorization URL: clickable link
• Token URL: shown for reference
• Scopes: collapsible list with descriptions
• Token paste input: paste the token obtained from the OAuth2 flow

The pasted token is injected as a Bearer token in snippets and Try-It. This is a passthrough; the plugin does not perform the OAuth2 redirect flow itself.

components:
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read:users: Read user data
            write:users: Modify user data

Programmatic access

For custom layouts or integrations outside of <OpenApiEndpoint>:

import { useAuthState, readStoredCredential } from 'vitepress-openapi-docs'

// Reactive (composable)
const auth = useAuthState('api')
auth.set({ scheme: 'bearer', value: 'my-token' })
auth.clear()

// Synchronous read
const cred = readStoredCredential('api')