Authentication

Auto-populate API keys

Make integrating with your API frictionless by adding your login flow to the API Explorer.

This feature is available on the Pro plan. Contact us to learn more.

Fern can integrate with your authentication flow, allowing users to login and have their API key automatically populated with the click of a button.

With this feature, you can create new users of your API directly from within your documentation.

Integrating with your auth flow

API key injection can work in two different ways depending on your company’s authentication setup: JWT or OAuth.

  • JWT Flow: You handle the entire auth flow and just give Fern a JWT cookie
  • OAuth Flow: You give Fern access, and Fern directly initiates the OAuth handshake process

How the JWT flow works

To enable this feature, you need to configure authentication so that Fern can securely retrieve API keys for your users. The process works as follows:

  1. When a user clicks the “Login” button in the API Explorer, they are redirected to your authentication page.
  2. After successful authentication, your system must set a cookie called fern_token in the user’s browser.
  3. This token should be a JWT encrypted with a secret key that we provide. The JWT should contain the user’s API key.

The JWT should have a structure similar to:

1{
2  "fern": {
3    "playground": {
4      "initial_state": {
5        "auth": {
6          "bearer_token": "eyJhbGciOiJIUzI1c"
7        }
8      }
9    }
10  }
11}

Architecture diagram

Setting up auto-populated API keys

  • Reach out to Fern to get your secret key
  • Send Fern the URL of your authentication page. This is where users will be redirected to after clicking the “Login” button in the API Explorer.
  • Add logic to your service to set the fern_token cookie when a user logs in
For an example of how to set up the fern_token cookie, see our demo implementation here.

How the OAuth flow works

To enable this feature, you need to configure OAuth authentication so that Fern can securely retrieve API keys for your users through your OAuth provider. Here’s how the process works:

  1. When a user clicks the “Login” button in the API Explorer, Fern initiates an OAuth flow by making a request to your authorization endpoint.
  2. The user is redirected to your OAuth provider’s login page where they authenticate using your existing auth system.
  3. After successful authentication, your OAuth provider redirects back to Fern with an authorization code, which Fern exchanges for an access token at your token endpoint.
  4. Fern sets a fern_token cookie containing the user’s authentication credentials and automatically populates their API key in the API Explorer.

Architecture diagram

Setting up auto-populated API keys

To enable API key injection, you’ll need to:

  • Set up an authenticated account for Fern so Fern can authorize users on your behalf.
  • Configure your OAuth application to return user API keys when Fern requests them

Then, you’ll need to send Fern the following items:

  • The client ID and client secret for Fern’s authenticated account
  • The URL of your authentication endpoint. This is where users will be redirected to after clicking the “Login” button in the API Explorer.
  • The URL of your token endpoint. This is where Fern exchanges codes for tokens.