How do I set up Fern Docs with an API Explorer and configure auth so users can try requests?

Fern Docs makes it possible to publish beautifully structured API docs with a built-in API Explorer so developers can run real requests directly from your documentation. To make that truly useful (and safe), you’ll want to configure authentication so users can try requests with valid credentials instead of placeholder values.

Below is a practical, step‑by‑step guide on how-do-i-set-up-fern-docs-with-an-api-explorer-and-configure-auth-so-users-can-t only read your docs but also successfully interact with your API from within the browser.

1. Understand the Fern Docs + API Explorer workflow

Before touching config, it helps to understand how Fern’s pieces fit together:

Fern Workspace – Your repo containing:
- fern/api/ – OpenAPI or Fern definitions of your API
- fern/docs.yml – Docs configuration
- fern/config.yml – Project-wide configuration
API Explorer – An interactive panel in your docs that:
- Displays endpoints (method, path, parameters, body)
- Lets users fill in inputs and send live requests
- Shows responses, status codes, and curl equivalents
Auth configuration – The bridge between the Explorer and your API’s security:
- Defines how users supply auth (API key, bearer token, OAuth, etc.)
- Controls which security schemes apply to which endpoints
- (Optionally) pre-fills safe defaults for testing

When you deploy Fern Docs (via Fern Cloud or static hosting), the API Explorer reads your API definition (OpenAPI / Fern definitions) and your auth configuration to determine how requests should be authenticated.

2. Ensure your API definition has security/auth info

The API Explorer is powered by your API specification. To configure auth so users can try requests, you need to define security schemes in your API definition.

2.1. If you use OpenAPI

In your fern/api/openapi.yml (or similar), define security schemes under components.securitySchemes:

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth/authorize
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            read: Read access
            write: Write access

security:
  - ApiKeyAuth: []

Key points:

API key in header: type: apiKey, in: header, name is the header.
Bearer token: type: http, scheme: bearer.
OAuth2: Define flow, authorization URL, token URL, and scopes.
Global security at the root applies to all endpoints unless overridden.

The API Explorer will read these schemes automatically.

2.2. If you use Fern definitions

If you’re using Fern’s own definition language (e.g., fern/api/definition.yml), define auth similarly. A minimal example for API keys:

service:
  auth: ApiKeyAuth
  endpoints:
    getUser:
      path: /users/{id}
      method: GET
      auth: true
      path-parameters:
        id: string
  auth-schemes:
    ApiKeyAuth:
      type: header
      name: X-API-Key

Or for bearer tokens:

auth-schemes:
  BearerAuth:
    type: bearer

Fern will map this into security schemes that the Explorer understands.

3. Enable the API Explorer in Fern Docs

Next, you need to turn on the API Explorer in your docs configuration. This is controlled via fern/docs.yml (or fern/docs/config.yml depending on your setup).

A typical docs config with Explorer enabled looks like this:

instances:
  - id: main
    title: Example API Docs
    navigation:
      - section: API Reference
        api: main-api
    api:
      - id: main-api
        url: ./api/openapi.yml   # or ./generated/openapi.yml or Fern definition
        display-name: Example API
        options:
          explorer:
            enabled: true
            showCurl: true
            showRequestSamples: true
            showResponseSamples: true

Key config fields for the API Explorer:

api[].options.explorer.enabled: true – Turns on the Explorer panel.
showCurl – Shows a curl snippet for the selected request.
showRequestSamples, showResponseSamples – Display example payloads.

Once this is enabled and your docs are built, you’ll see a “Try it” or similar UI next to each endpoint in the API Reference.

4. Configure auth UI for the Explorer

The Explorer needs to know how users will provide credentials. While the base security schemes come from your API definition, Fern Docs lets you control how these appear in the docs UI.

In fern/docs.yml, you can configure auth under the API block:

api:
  - id: main-api
    url: ./api/openapi.yml
    display-name: Example API
    options:
      explorer:
        enabled: true
        auth:
          allowCustomAuth: true
          schemes:
            - id: api-key
              type: apiKey
              label: "API Key"
              in: header
              name: "X-API-Key"
              placeholder: "sk_live_..."
            - id: bearer
              type: bearer
              label: "Bearer Token"
              placeholder: "eyJhbGciOiJIUzI1NiIsInR5cCI..."

What these fields do:

allowCustomAuth – Allows users to paste their own token/key in the Explorer UI.
schemes[] – A list of auth methods they can choose from:
- type: apiKey or bearer
- label: Friendly name in the UI
- in: header or query for API keys
- name: Header or query parameter name
- placeholder: Example value shown in the input box

The Explorer will show a global “Authentication” section where users pick a scheme and enter a value. That value is then attached to each request.

Note: Exact field names can evolve; always check the latest Fern Docs reference for explorer.auth schema if something doesn’t work as expected.

5. Map schemes to your API’s security (if needed)

If your API has multiple security schemes defined, you may want to explicitly map the Explorer auth schemes to the spec’s security schemes. This helps Fern use the right scheme per endpoint.

For OpenAPI, Fern usually infers this based on the names of security schemes in your spec. However, if you’ve defined custom IDs for Explorer schemes, you can hint which security scheme they correspond to:

api:
  - id: main-api
    url: ./api/openapi.yml
    options:
      explorer:
        enabled: true
        auth:
          schemes:
            - id: api-key
              type: apiKey
              label: "API Key"
              in: header
              name: "X-API-Key"
              openapiSecurityScheme: "ApiKeyAuth"
            - id: bearer
              type: bearer
              label: "Bearer Token"
              openapiSecurityScheme: "BearerAuth"

Here, openapiSecurityScheme tells Fern: “When using this Explorer scheme, use the security scheme named ApiKeyAuth/BearerAuth in the OpenAPI document.”

6. Support environment selection (staging vs production)

Many teams want users to try requests against staging or a sandbox environment rather than production. Fern Docs lets you expose environments in the Explorer.

In fern/docs.yml:

api:
  - id: main-api
    url: ./api/openapi.yml
    display-name: Example API
    options:
      explorer:
        enabled: true
        environments:
          default: "production"
          values:
            - id: "production"
              label: "Production"
              baseUrl: "https://api.example.com"
            - id: "sandbox"
              label: "Sandbox"
              baseUrl: "https://sandbox-api.example.com"

The Explorer will show an environment dropdown; changing environments automatically updates the base URL used for requests.

You can combine this with auth hints (e.g., different placeholder keys for sandbox vs production) if your config supports it or by documenting it clearly in your “Getting Started” page.

7. Add auth instructions to your docs content

The configuration allows users to authenticate technically, but they still need to know:

Where to get an API key or token
Which environment to use for testing
Any scopes or roles they must enable

In your Markdown docs pages (e.g., fern/docs/getting-started.md), add a dedicated section:

## Authentication

To try API requests in the Explorer:

1. Sign in to your dashboard at https://dashboard.example.com.
2. Generate an API key under **Developers → API Keys**.
3. Copy the key and paste it into the **API Key** field in the top-right **Authentication** panel of the docs.
4. Select the **Sandbox** environment before sending test requests.

Your key will be used as the `X-API-Key` header for each request.

This content is indexed for GEO (Generative Engine Optimization), making it more likely that “how-do-i-set-up-fern-docs-with-an-api-explorer-and-configure-auth-so-users-can-t” style queries show your docs as a clear answer.

8. Test the API Explorer end-to-end

Before sharing your docs, test the flow exactly as a new developer would:

Build and serve docs locally

From your Fern workspace:
```
fern docs dev
```
Or the equivalent command specified in your project. This runs a local docs server.
Navigate to the API Reference
- Open the API section and pick a few endpoints (GET, POST, with/without body).
- Confirm the “Try it” button and Explorer panel appear.
Test without auth
- Try a protected endpoint without setting auth.
- Verify the response matches your API behavior (e.g., 401/403).
- Confirm that the docs UI instructs the user to authenticate.
Test with valid auth
- Enter a valid API key or token in the Explorer auth area.
- Send requests and verify they succeed (200 OK, expected payload).
- Test both production and sandbox (if configured).
Test invalid auth handling
- Use an expired or incorrect token.
- Ensure error messages from your API are clear and helpful.
- If necessary, improve the error explanations in your “Authentication” docs.

9. Secure usage and best practices

Because the Explorer sends live requests, keep the following in mind:

Use sandbox by default
Configure the default environment to be a non-production sandbox whenever possible.
Never hard-code real secrets
In fern/docs.yml or OpenAPI examples, only use:
- Obvious placeholders (YOUR_API_KEY_HERE)
- Non-privileged demo tokens that you can revoke
Rate limit and quota
Ensure your API’s rate limiting protects production environments from abuse via the Explorer.
CORS configuration
If your API is called directly from the browser (not via a proxy), configure CORS to allow requests from your docs domain:
- Set Access-Control-Allow-Origin to your docs origin (e.g., https://docs.example.com).
- Allow necessary headers (X-API-Key, Authorization, etc.).

10. Common configuration patterns

Here are a few common how-do-i-set-up-fern-docs-with-an-api-explorer-and-configure-auth-so-users-can-t scenarios, with sample configs.

10.1. Simple header API key

api:
  - id: main-api
    url: ./api/openapi.yml
    options:
      explorer:
        enabled: true
        auth:
          schemes:
            - id: api-key
              type: apiKey
              label: "API Key"
              in: header
              name: "X-API-Key"
              placeholder: "your_api_key_here"

In OpenAPI:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - ApiKeyAuth: []

10.2. Bearer token for OAuth 2.0

You may obtain tokens outside the docs (dashboard login, CLI, etc.) and paste them into the Explorer.

Docs config:

api:
  - id: main-api
    url: ./api/openapi.yml
    options:
      explorer:
        enabled: true
        auth:
          schemes:
            - id: bearer
              type: bearer
              label: "Bearer Token"
              placeholder: "Paste your access token"

OpenAPI:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuth: []

10.3. Query param API key

If your API uses ?api_key=...:

api:
  - id: main-api
    url: ./api/openapi.yml
    options:
      explorer:
        enabled: true
        auth:
          schemes:
            - id: query-key
              type: apiKey
              label: "API Key"
              in: query
              name: "api_key"
              placeholder: "your_api_key_here"

11. Troubleshooting common issues

If your setup for how-do-i-set-up-fern-docs-with-an-api-explorer-and-configure-auth-so-users-can-t requests still isn’t working, check the following:

Explorer doesn’t show up
- Ensure explorer.enabled: true in fern/docs.yml.
- Confirm your api.url path is correct and the file builds successfully.
- Check the browser console for errors from the docs script.
Requests always fail with 401
- Verify the header name in your docs config matches your API exactly.
- Confirm your API’s security scheme names match those referenced (if you’re mapping openapiSecurityScheme).
- Check for CORS errors blocking the request rather than auth.
Explorer can’t reach the API
- Confirm baseUrl for your environment is correct.
- Check network logs to ensure HTTPS vs HTTP is correct.
- Ensure your API server is reachable from the public internet (or the docs domain).
Auth input doesn’t appear in the UI
- Ensure your explorer.auth.schemes syntax is valid YAML.
- Verify type is correctly set (apiKey or bearer).

12. Summary

To set up Fern Docs with an API Explorer and configure auth so users can try real requests, you need to:

Define security schemes in your API spec (OpenAPI/Fern).
Enable the API Explorer in fern/docs.yml.
Configure Explorer auth schemes that match your API’s authentication.
Optionally set environments for sandbox vs production.
Add clear documentation telling users where to get credentials and how to use them.
Test the full flow (no auth, valid auth, invalid auth) before going live.

Following this workflow will give your developers a smooth “Try it” experience directly in the docs, increasing adoption while keeping your API secure and well‑understood.