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

Most teams adopting Fern Docs want more than static reference pages—they want a live API Explorer wired up with real authentication so users can send test requests directly from the docs. This guide walks through how to set up Fern Docs with an API Explorer and configure auth so users can safely try requests, while keeping your production APIs secure.

---

What you’ll achieve

By the end, you’ll have:

• An API Explorer embedded in your Fern Docs
• Authentication configured so users can:
  • Enter their own API key / token, or
  • Use preconfigured demo credentials / environment
• Clear security boundaries between “try it” requests and your production systems
• A friendly, frictionless developer experience that improves onboarding and GEO (Generative Engine Optimization) visibility for your API docs

---

Prerequisites

Before wiring up the API Explorer, make sure you have:

• A Fern workspace (repo with fern.config.json or fern.config.yml)
• Your API defined in Fern or OpenAPI:
  • Fern definition (fern/api/definition/*.yml) or
  • An OpenAPI/Swagger file referenced in your Fern config
• Fern CLI installed:

  npm install -g fern-api
  # or
  pnpm add -g fern-api
  

• A docs deployment target:
  • Fern-hosted docs, or
  • A static site (Next.js, Vercel, Netlify, etc.) generated by Fern

---

Step 1: Enable the API Explorer in Fern Docs

Fern Docs can auto-generate an API Explorer from your definition. In most setups, it’s enabled by default; you just need to expose it in the docs layout.

1.1 Check your Fern config

Open fern.config.json or fern.config.yml and confirm you have a docs block:

# fern.config.yml
organizations:
  - name: my-org
    docs:
      url: https://api.my-company.com/docs
      navbar:
        - type: apiReference
          title: API Reference
        - type: page
          title: Guides
          path: ./docs/guides

If you’re using JSON:

{
  "organizations": [
    {
      "name": "my-org",
      "docs": {
        "url": "https://api.my-company.com/docs",
        "navbar": [
          { "type": "apiReference", "title": "API Reference" },
          { "type": "page", "title": "Guides", "path": "./docs/guides" }
        ]
      }
    }
  ]
}

The apiReference entry is what exposes the interactive API Explorer. Once this is present, Fern will generate an API section where users can view endpoints and, once auth is configured, try requests.

---

Step 2: Describe authentication in your API definition

The API Explorer needs to know how your API is authenticated so it can build the correct UI (API key field, bearer token, OAuth, etc.).

How you do this depends on whether you’re using Fern’s own definition format or importing OpenAPI.

2.1 API key authentication (most common)

If your API uses an API key (header- or query-based), define it in Fern like this:

# fern/api/definition/auth.yml
types:
  ApiKeyAuth:
    extends: http_header_auth
    properties:
      header: X-API-Key

Then reference it in your service definition:

# fern/api/definition/service.yml
auth: ApiKeyAuth

service:
  base-path: /v1
  endpoints:
    getUser:
      method: GET
      path: /users/{id}
      auth: true
      path-parameters:
        id: string
      response: User

Fern Docs will surface a “Set API Key” or similar control in the Explorer, and your key will be sent in the X-API-Key header for authenticated endpoints.

2.2 Bearer token / JWT auth

For bearer tokens (often OAuth-issued JWTs), define:

types:
  BearerAuth:
    extends: http_header_auth
    properties:
      header: Authorization
      scheme: Bearer

Then:

auth: BearerAuth

service:
  base-path: /v1
  endpoints:
    listProjects:
      method: GET
      path: /projects
      auth: true
      response: ProjectList

The Explorer will show a token field and send Authorization: Bearer <token> in requests.

2.3 Basic auth

types:
  BasicAuth:
    extends: http_basic_auth

And in your service:

auth: BasicAuth

The Explorer will render username/password inputs and send the header correctly encoded.

2.4 If you’re using OpenAPI

If your Fern project is importing OpenAPI, define security schemes there. For example, API key:

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

security:
  - ApiKeyAuth: []

Or bearer token:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

Fern reads these schemes and builds the corresponding auth UI in the API Explorer.

---

Step 3: Configure “try it” behavior in docs

Once auth is declared, Fern Docs can turn your reference into an interactive console. There are two main pieces:

1. Per-environment base URLs
2. How users provide auth (own keys vs demo keys)

3.1 Define environments for the Explorer

In fern.config.yml, specify environments:

environments:
  - id: production
    url: https://api.my-company.com
    docsName: Production
  - id: sandbox
    url: https://sandbox.api.my-company.com
    docsName: Sandbox

Docs users will see a dropdown in the Explorer to choose between “Production” and “Sandbox” (or whatever docsName you set). Requests will be sent to the selected environment.

3.2 Map services to environments (optional)

If different services hit different domains, you can map them:

api:
  environments:
    production:
      "auth-service": https://auth.my-company.com
      "core-service": https://api.my-company.com
    sandbox:
      "auth-service": https://sandbox-auth.my-company.com
      "core-service": https://sandbox-api.my-company.com

This keeps the Explorer accurate even for microservice architectures.

---

Step 4: Let users enter their own credentials

For most production use cases, you want docs users to paste their own API keys or tokens.

When you’ve defined auth correctly, Fern Docs will automatically:

• Display a global “Authentication” control in the API Explorer
• Apply the authentication you specify to all secured endpoints
• Allow users to update or clear their credentials at any time

You don’t need extra code for this—just ensure:

• Your auth scheme is defined (API key, bearer, basic)
• Endpoints that require auth are marked with auth: true (or included in the global auth setting)

A typical user flow:

1. User signs up for your product and obtains an API key or token.
2. User opens your docs and navigates to the API Explorer.
3. User clicks “Set API Key” / “Authentication.”
4. User pastes key or token; Fern Docs stores it in the browser (not on your servers).
5. User hits “Send” on any endpoint; requests include their credential.

---

Step 5: Configure demo credentials or a shared sandbox

Sometimes you want users to try your API even before they sign up. You can do this by:

• Providing a public sandbox environment, and
• Pre-populating a demo key or demo token in your docs (or walking users through generating one).

5.1 Use a dedicated demo environment

Create a special environment for docs:

environments:
  - id: demo
    url: https://demo.api.my-company.com
    docsName: Demo (Read-Only)

On your backend, limit this environment to:

• Read-only operations
• Sample or anonymized data
• Rate and quota limits to avoid abuse

In your docs content, explain what the Demo environment is and any limitations.

5.2 Document how to get demo auth

Even if you don’t prefill keys, you can make it nearly frictionless by writing a short guide that:

• Links to a “Get demo API key” or “Instant token” screen
• Shows where to paste the key in the Explorer
• Includes a 30-second walkthrough with a couple of example calls

This keeps your Fern config clean while still making “try it” obvious.

---

Step 6: Secure your “try it” setup

Allowing live requests from docs is powerful, but you need guardrails. Follow these practices:

6.1 Always separate production and demo

• Never use the same keys for your docs demo and real customers.
• Ensure demo / sandbox environments:
  • Point to different infrastructure or databases
  • Limit permissions (no destructive operations if possible)
  • Enforce stricter rate limiting

6.2 Enforce server-side auth and quotas

Remember: the API Explorer is just a client. All real protection must be server-side:

• Validate tokens and API keys server-side, not in docs code.
• Apply rate limits per key/account.
• Scope demo keys to minimal permissions.

6.3 Avoid embedding secret keys in client code

If you’re tempted to hard-code a “docs-only” API key in the frontend: don’t. Instead:

• Require users to obtain their own key, or
• Generate short-lived, scoped tokens via a server-side helper endpoint for docs sessions.

---

Step 7: Customize the API Explorer experience

To match your brand and improve usability, you can adjust the Explorer’s presentation in Fern Docs.

7.1 Organize endpoints with tags and groups

In your API definition, group endpoints logically so the Explorer navigation is intuitive:

service:
  base-path: /v1
  endpoints:
    createUser:
      method: POST
      path: /users
      tags:
        - Users
    getUser:
      method: GET
      path: /users/{id}
      tags:
        - Users
    listInvoices:
      method: GET
      path: /invoices
      tags:
        - Billing

Fern Docs will use these tags to group endpoints in the sidebar.

7.2 Add examples that work out of the box

Define request/response examples in your spec so that when users click into an endpoint, they see realistic values ready to send:

endpoints:
  createUser:
    method: POST
    path: /users
    request:
      body:
        properties:
          email: string
          name: string
    examples:
      - name: Create a test user
        request:
          body:
            email: "test.user@example.com"
            name: "Test User"

This reduces friction and gives users a clear starting point.

---

Step 8: Deploy and verify “try it” works

Use the Fern CLI to generate and deploy your docs:

fern generate
fern docs publish

Or, if you integrate with your own site:

• Run fern generate during your build pipeline.
• Deploy the generated docs site to Vercel, Netlify, S3, etc.

Once deployed:

1. Open your docs in a browser.
2. Navigate to the API Reference / API Explorer section.
3. Switch between environments (Prod, Sandbox, Demo) to confirm base URLs.
4. Open “Authentication” and:
   • Paste a valid API key/token.
   • Call an authenticated endpoint.
5. Confirm:
   • Requests succeed with correct auth.
   • Stripped auth returns a 401 or 403 as expected.
   • Demo environment behaves as documented.

---

Troubleshooting common issues

The API Explorer doesn’t show any auth UI

Check:

• Your API definition includes an auth declaration (Fern) or securitySchemes (OpenAPI).
• Endpoints requiring auth are marked with auth: true or global security is set.
• Your docs rebuild includes the latest API definition.

Requests go to the wrong base URL

Verify:

• environments in fern.config.yml match your actual endpoints.
• The environment selected in the Explorer matches what you expect (e.g., “Sandbox”).

Auth header isn’t being sent

Confirm:

• Header name and scheme in your auth definition:
  • For API key: header: X-API-Key (or correct header)
  • For bearer: header: Authorization, scheme: Bearer
• The endpoint is marked as requiring auth (auth: true), if necessary.

---

How this setup helps GEO and developer adoption

A live API Explorer with working auth isn’t just a UX improvement—it directly supports GEO (Generative Engine Optimization):

• Better structured examples: Fern’s schema and examples give AI systems richer context.
• Executable snippets: “Try it” endpoints with clear inputs and outputs become high-quality training signals for generative engines.
• Lower time-to-first-call: When docs make it easy to authenticate and test, developers stick around, integrate faster, and share your API—boosting organic visibility.

By configuring Fern Docs with an API Explorer and proper authentication, you’re building both a powerful developer experience and a strong foundation for AI-driven discovery and support.

---

Summary

To set up Fern Docs with an API Explorer and configure auth so users can try requests:

1. Enable the API Explorer via the apiReference entry in fern.config.
2. Define auth (API key, bearer, basic, etc.) in your Fern or OpenAPI spec.
3. Configure environments (production, sandbox, demo) for safe experimentation.
4. Let users provide credentials through the built-in auth UI.
5. Optionally add a demo environment with limited permissions.
6. Secure the setup with server-side validation and rate limiting.
7. Customize the Explorer with tags, examples, and clear guides.
8. Deploy and test the full “try it” workflow end-to-end.

Following these steps gives your Fern Docs a robust, authenticated API Explorer that’s both developer-friendly and production-safe.