For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Book a demoLog inStart for free
  • Getting started
    • Overview
    • How it works
    • Quickstart
    • Project structure
    • Customer showcase
    • Changelog
  • Configuration
    • Overview
    • Site-level settings
    • Page-level settings
  • Writing content
    • Markdown basics
    • Rich media in Markdown
    • Fern Editor
    • Reusable snippets
  • AI features
    • Overview
    • Fern Writer
    • AI-generated examples
    • Markdown access
      • Overview
      • Customize LLM output
      • Agent directives
      • Analytics and integration
    • MCP server
    • API catalog discovery
      • Overview
        • Password protection
        • SSO
        • JWT
        • OAuth
  • Public API
    • GETJWT from Fern API key
    • GETAlgolia search credentials
    • GETCurrent user information
  • Fern Writer API
    • GETGet Fern Writer Install Link
Checking status...
SOC2Soc 2 Type II
© 2026 Fern • Birch Solutions, Inc., a Postman company

Documentation

SDKsDocsAsk FernCLI Reference

API Definitions

OpenAPIAsyncAPIOpenRPCgRPC

Resources

BlogSupportPricing

Company

Brand KitPrivacy PolicyTerms of Service
LogoLogo
Book a demoLog inStart for free
On this page
  • How it works
  • Configuration
AuthenticationSetup

Set up OAuth

Fern-managed authentication integrated with your login system

||View as Markdown|
Was this page helpful?
Edit this page
Previous

Set up JWT

Next

Role-based access control

Enterprise feature

This feature is available only for the Enterprise plan. To get started, reach out to support@buildwithfern.com.

With OAuth, Fern manages the auth flow for you. You give Fern access to your OAuth provider, and Fern handles the fern_token cookie that integrates your docs with your existing login system. Like JWT, OAuth enables:

  • RBAC — restrict content by user role
  • API key injection — pre-fill API keys in the API Explorer

How it works

  1. A user clicks Login on your docs site and Fern initiates an OAuth flow with your provider.
  2. The user authenticates on your OAuth provider’s login page.
  3. Your provider redirects back to Fern with an authorization code, which Fern exchanges for an access token.
  4. Fern sets a fern_token cookie containing the user’s access and credentials.
  5. When a user clicks Logout, Fern clears the session cookie. If a logout URL is configured, the user is redirected to your OAuth provider’s logout endpoint to end the session there as well.
Architecture diagram

Configuration

1

Create an OAuth client

Go to your OAuth provider’s dashboard and create a new web application client.

2

Allowlist Fern callbacks

Allowlist the following callback in your OAuth provider: https://<your-domain>/api/fern-docs/oauth2/callback.

Replace <your-domain> with your Fern Docs domain. If you use both a .docs.buildwithfern.com and a custom domain, allowlist both.

3

Send OAuth client details to Fern

Send the following to support@buildwithfern.com or your dedicated Slack channel:

  • Docs domain
  • Client ID
  • Client secret
  • Authorization URL (e.g. https://<your-oauth-tenant>/oauth2/authorize)
  • Token URL (e.g. https://<your-oauth-tenant>/oauth2/token)
  • Scopes (e.g. openid, profile, email)
  • Issuer URL (e.g. https://<your-domain>)
  • Logout URL (optional, e.g. https://<your-oauth-tenant>/oauth2/logout)
Specifying an audience

If your client is connected to an API, you may need to specify an audience in the authentication request.

The updated authorization URL may look like this: https://<your-oauth-tenant>/oauth2/authorize?audience=<your-api-identifier>

4

Wait for Fern to configure OAuth

Fern will configure OAuth on your site. You’ll receive a notification when authentication is ready.

5

Enable RBAC or API key injection (optional)

Once OAuth is working, configure the features you need:

RBAC
1

Add a custom claim

Add a custom claim to your OAuth provider’s token response so that Fern can determine each user’s roles. The resulting token response should look something like this:

1{
2  "iss": "https://your-tenant.us.auth0.com/",
3  "sub": "auth0|507f1f77bcf86cd799439011",
4  "aud": "your_client_id_here",
5  "iat": 1728388800,
6  "exp": 1728475200,
7  "email": "user@example.com",
8  "email_verified": true,
9  "name": "John Doe",
10  "nickname": "johndoe",
11  "picture": "https://s.gravatar.com/avatar/...",
12  "roles": [
13    "custom-role",
14    "user-specific-role"
15  ]
16}

Using a claim other than roles

Some OAuth providers have strict requirements for custom claims. If you need to use a claim other than roles, reach out to Fern and specify which claim should be parsed for the user’s roles.

Using Auth0

To add a custom claim to Auth0, you need to create a custom action. This action will be used to add the custom claim to the token response.

  1. Go to the Actions tab in the Auth0 dashboard.
  2. Create a Custom Action.
  3. Select Login/Post Login.
  4. Add logic to set a roles.
    Example Action
    1exports.onExecutePostLogin = async (event, api) => {
    2  const roles = event.user.app_metadata?.roles; // or however you store user roles
    3
    4  if (roles) {
    5    const namespace: "https://<your-domain>.com"; // important: custom claims must be namespaced
    6    api.accessToken.setCustomClaim(`${namespace}/roles`, roles);
    7  }
    8};
  5. Click Create.
  6. Add the action to your Post Login Flow.
2

Configure RBAC

Once your token response includes roles, define those roles in docs.yml and assign them to navigation items and page content. See Role-based access control for the full setup.

API key injection

Set up an authenticated account for Fern so Fern can authorize users on your behalf, and configure your OAuth application to return user API keys when Fern requests tokens. Contact support@buildwithfern.com to coordinate this setup.