身份验证 | Fern Documentation

身份验证方案的配置在 api.yml 文件中进行。所有 Fern 生成的 SDK 都支持身份验证凭据的直接配置和环境变量配置。

fern/
├─ fern.config.json # 根级配置
├─ generators.yml # 您正在使用的生成器
└─ definition/
  ├─ api.yml  # API 级配置
  └─ imdb.yml # 端点、类型和错误

要添加身份验证方案，请在 auth-schemes 部分下指定身份验证方法。

api.yml

auth-schemes:
  AuthScheme:                     
    ...

要在所有端点应用身份验证方案，请在 api.yml 文件的 auth 部分中引用 auth-scheme。

api.yml

auth: AuthScheme                  
auth-schemes:
  AuthScheme:                     
    ...

Bearer 身份验证

首先在 api.yml 中定义一个 Bearer 身份验证方案：

api.yml

auth: Bearer                  
auth-schemes:
  Bearer:                     
    scheme: bearer

这将生成一个 SDK，用户必须提供一个名为 token 的必需参数。

index.ts

const client = new Client({
  token: "ey34..."
})

如果您想控制变量命名和要扫描的环境变量，请使用以下配置：

api.yml

auth: Bearer                  
auth-schemes:
  Bearer:                     
    scheme: bearer
    token:
      name: apiKey 
      env: PLANTSTORE_API_KEY

生成的 SDK 将如下所示：

index.ts

// 使用 process.env.PLANTSTORE_API_KEY
let client = new Client(); 
// token 已重命名为 apiKey
client = new Client({
  apiKey: "ey34..."
})

基本身份验证

首先在 api.yml 中定义一个 Basic 身份验证方案：

api.yml

auth: Basic                  
auth-schemes:
  Basic:                     
    scheme: basic

这将生成一个 SDK，用户必须提供名为 username 和 password 的必需参数。

index.ts

const client = new Client({
  username: "joeschmoe"
  password: "ey34..."
})

如果您想控制变量命名和要扫描的环境变量，请使用以下配置：

api.yml

auth: Basic                  
auth-schemes:
  Basic:                     
    scheme: basic
    username:
      name: clientId
      env: PLANTSTORE_CLIENT_ID
    password:
      name: clientSecret
      env: PLANTSTORE_CLIENT_SECRET

生成的 SDK 将如下所示：

index.ts

// 使用 process.env.PLANTSTORE_CLIENT_ID 和 process.env.PLANTSTORE_CLIENT_SECRET
let client = new Client(); 
// 参数已重命名
client = new Client({
  clientId: "joeschmoe", 
  clientSecret: "ey34..."
})

自定义标头（例如 API key）

您还可以使用自定义标头创建自己的身份验证方案。

api.yml

auth: ApiKeyAuthScheme
auth-schemes:
  ApiKeyAuthScheme:
    header: X-API-Key
    type: string

这将生成一个 SDK，用户必须提供一个名为 apiKey 的必需参数。

index.ts

const client = new Client({
  xApiKey: "ey34..."
})

如果您想控制变量命名和要扫描的环境变量，请使用以下配置：

api.yml

auth: ApiKeyAuthScheme
auth-schemes:
  ApiKeyAuthScheme:
    header: X-API-Key
    type: string
    name: apiKey
    env: PLANTSTORE_API_KEY

生成的 SDK 将如下所示：

index.ts

// 使用 process.env.PLANTSTORE_API_KEY
let client = new Client(); 
// 参数已重命名
client = new Client({
  apiKey: "ey34..."
})

OAuth 客户端凭据

团队版和企业版功能

此功能仅适用于团队版和企业版计划。要开始使用，请联系 support@buildwithfern.com。

如果您的 API 使用 OAuth，您可以在 api.yml 中指定 oauth 方案，并在单独的 auth.yml 文件中定义令牌检索端点（示例）。

api.yml

name: api
imports:
  auth: auth.yml
auth: OAuthScheme
auth-schemes:
  OAuthScheme:
    scheme: oauth
    type: client-credentials
    client-id-env: YOUR_CLIENT_ID
    client-secret-env: YOUR_CLIENT_SECRET
    get-token:
      endpoint: auth.getTokenWithClientCredentials
      request-properties:
        client-id: $request.client_id         # 格式：参数名: $request.属性名
        client-secret: $request.client_secret # 格式：参数名: $request.属性名            
      response-properties:
        access-token: $response.access_token  # 格式：参数名: $response.属性名
        expires-in: $response.expires_in      # 格式：参数名: $response.属性名

request-properties 和 response-properties 将 OAuth 标准参数映射到您在 auth.yml 中定义的实际端点的请求和响应字段名称。

如果设置了 expires-in 属性，生成的 OAuth 令牌提供程序将在令牌过期时自动刷新令牌。否则，假设访问令牌是永久有效的。

相应的 auth.yml 文件（示例）定义了令牌端点：

auth.yml

types:
  TokenResponse:
    docs: |
      OAuth 令牌响应。
    properties:
      access_token: string
      expires_in: integer
      refresh_token: optional<string>
service:
  auth: false
  base-path: /
  endpoints:
    getTokenWithClientCredentials:
      path: /token
      method: POST
      request:
        name: GetTokenRequest
        body:
          properties:
            client_id: string
            client_secret: string
            audience: literal<"https://api.example.com">
            grant_type: literal<"client_credentials">
            scope: optional<string>
      response: TokenResponse

如果您的 OAuth 服务器托管在与主 API 不同的 URL 上，您可以使用每个环境多 URL 来为身份验证和 API 调用指定单独的基础 URL。

有了这些设置，所有 OAuth 逻辑会在生成的 SDK 中自动处理。只要您配置了这些设置，您的客户端将自动检索访问令牌并根据需要刷新它。

在使用文档操作界面时，可以选择性地设置 token-header 和 token-prefix 来自定义标头键名和标头值前缀，以匹配 API 身份验证方案的预期格式。

例如，以下配置将产生标头 Fern-Authorization: Fern-Bearer <token>：

api.yml

auth-schemes:
  OAuthScheme:
    scheme: oauth
    type: client-credentials
    token-header: Fern-Authorization
    token-prefix: Fern-Bearer
    get-token:
      ...