AuthenticationFeatures

API key injection

Automatically populate API keys in the API Explorer for logged-in users.

View as Markdown
Pro and Enterprise feature

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

API key injection is a feature of JWT and OAuth authentication. When a user logs in, a fern_token cookie is set in their browser with a fern.playground claim that tells the API Explorer what values to pre-fill — API keys, headers, or other credentials. You can combine it with RBAC in a single token.

User credentials are stored only in browser cookies and never transmitted to Fern’s servers. Learn more in the Security overview.

Setup

To enable API key injection, follow the JWT or OAuth setup guide.

Advanced payload configuration

With JWT setup, you have full control over the fern.playground payload. These options let you go beyond a single bearer token — pre-filling custom headers, supporting multiple API keys, or varying credentials by environment. These options are not available with OAuth, where Fern manages the token.

You can pre-fill headers, path parameters, and query parameters alongside auth credentials:

1{
2  "fern": {
3    "playground": {
4      "initial_state": {
5        "auth": {
6          "bearer_token": "eyJhbGciOiJIUzI1c"
7        },
8        "headers": {
9          "API-Version": "2024-02-02"
10        },
11        "path_parameters": {
12          "plantId": "plant_1234"
13        },
14        "query_parameters": {
15          "sort": "DESCENDING"
16        }
17      }
18    }
19  }
20}

To provide multiple API keys (for example, one per application), set bearer_token to a JSON-encoded array of key-value objects. Each object maps an application name to its key.

1{
2  "fern": {
3    "playground": {
4      "initial_state": {
5        "auth": {
6          "bearer_token": "[{\"Greenhouse app\": \"sk-greenhouse-abc123\"}, {\"Garden app\": \"sk-garden-def456\"}]"
7        }
8      }
9    }
10  }
11}

The API Explorer displays a dropdown so the user can choose which application key to use for requests.

Use env_state to provide different credentials for each environment (for example, production vs. staging). Each key in env_state is matched against the selected environment URL using substring matching.

1{
2  "fern": {
3    "playground": {
4      "initial_state": {
5        "auth": {
6          "bearer_token": "default-token"
7        }
8      },
9      "env_state": {
10        "prod": {
11          "auth": {
12            "bearer_token": "prod-token-abc123"
13          }
14        },
15        "staging": {
16          "auth": {
17            "bearer_token": "staging-token-def456"
18          }
19        }
20      }
21    }
22  }
23}

When the user selects an environment containing prod (such as https://api.prod.example.com), the API Explorer uses prod-token-abc123. The env_state values are merged on top of initial_state: auth is replaced entirely, while headers, path parameters, and query parameters are shallow-merged.