API key injection | Fern Documentation

企业功能

此功能仅适用于企业计划。如需开始使用，请联系 support@buildwithfern.com。

API key injection 是 JWT 和 OAuth 身份验证的一个功能。当用户登录时，会在其浏览器中设置一个 fern_token cookie，其中包含 fern.playground 声明，告诉 API Explorer 要预填充什么值——API keys、headers 或其他凭据。您可以将其与 RBAC 在单个令牌中结合使用。

用户凭据仅存储在浏览器 cookies 中，永远不会传输到 Fern 的服务器。了解更多信息请参阅安全概述。

设置

要启用 API key injection，请按照 JWT 或 OAuth 设置指南进行操作。

高级载荷配置

通过 JWT 设置，您可以完全控制 fern.playground 载荷。这些选项让您超越单个 bearer token——预填充自定义 headers、支持多个 API keys，或根据环境变化凭据。这些选项在 OAuth 中不可用，因为 Fern 管理令牌。

自定义 headers、路径参数和查询参数

您可以在身份验证凭据旁预填充 headers、路径参数和查询参数：

{
  "fern": {
    "playground": {
      "initial_state": {
        "auth": {
          "bearer_token": "eyJhbGciOiJIUzI1c"
        },
        "headers": {
          "API-Version": "2024-02-02"
        },
        "path_parameters": {
          "plantId": "plant_1234"
        },
        "query_parameters": {
          "sort": "DESCENDING"
        }
      }
    }
  }
}

多个 API keys

要提供多个 API keys（例如，每个应用程序一个），请将 bearer_token 设置为 JSON 编码的键值对象数组。每个对象将应用程序名称映射到其密钥。

{
  "fern": {
    "playground": {
      "initial_state": {
        "auth": {
          "bearer_token": "[{\"Greenhouse app\": \"sk-greenhouse-abc123\"}, {\"Garden app\": \"sk-garden-def456\"}]"
        }
      }
    }
  }
}

API Explorer 显示一个下拉菜单，用户可以选择使用哪个应用程序密钥进行请求。

按环境区分的密钥

使用 env_state 为每个环境提供不同的凭据（例如，生产环境与预发环境）。env_state 中的每个键都使用子字符串匹配与选定的环境 URL 进行匹配。

{
  "fern": {
    "playground": {
      "initial_state": {
        "auth": {
          "bearer_token": "default-token"
        }
      },
      "env_state": {
        "prod": {
          "auth": {
            "bearer_token": "prod-token-abc123"
          }
        },
        "staging": {
          "auth": {
            "bearer_token": "staging-token-def456"
          }
        }
      }
    }
  }
}

当用户选择包含 prod 的环境（如 https://api.prod.example.com）时，API Explorer 使用 prod-token-abc123。env_state 值会合并到 initial_state 之上：auth 完全替换，而 headers、路径参数和查询参数进行浅合并。