身份验证

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

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

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

api.yml

1 auth-schemes:
2   AuthScheme:                     
3     ...

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

api.yml

1 auth: AuthScheme                  
2 auth-schemes:
3   AuthScheme:                     
4     ...

Bearer 身份验证

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

api.yml

1 auth: Bearer                  
2 auth-schemes:
3   Bearer:                     
4     scheme: bearer

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

index.ts

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

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

api.yml

1 auth: Bearer                  
2 auth-schemes:
3   Bearer:                     
4     scheme: bearer
5     token:
6       name: apiKey 
7       env: PLANTSTORE_API_KEY

生成的 SDK 将如下所示：

index.ts

1 // 使用 process.env.PLANTSTORE_API_KEY
2 let client = new Client(); 
3 
4 // token 已重命名为 apiKey
5 client = new Client({
6   apiKey: "ey34..."
7 })

基本身份验证

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

api.yml

1 auth: Basic                  
2 auth-schemes:
3   Basic:                     
4     scheme: basic

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

index.ts

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

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

api.yml

1 auth: Basic                  
2 auth-schemes:
3   Basic:                     
4     scheme: basic
5     username:
6       name: clientId
7       env: PLANTSTORE_CLIENT_ID
8     password:
9       name: clientSecret
10       env: PLANTSTORE_CLIENT_SECRET

生成的 SDK 将如下所示：

index.ts

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

自定义标头（例如 API key）

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

api.yml

1 auth: ApiKeyAuthScheme
2 auth-schemes:
3   ApiKeyAuthScheme:
4     header: X-API-Key
5     type: string

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

index.ts

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

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

api.yml

1 auth: ApiKeyAuthScheme
2 auth-schemes:
3   ApiKeyAuthScheme:
4     header: X-API-Key
5     type: string
6     name: apiKey
7     env: PLANTSTORE_API_KEY

生成的 SDK 将如下所示：

index.ts

1 // 使用 process.env.PLANTSTORE_API_KEY
2 let client = new Client(); 
3 
4 // 参数已重命名
5 client = new Client({
6   apiKey: "ey34..."
7 })

OAuth 客户端凭据

团队版和企业版功能

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

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

api.yml

1 name: api
2 
3 imports:
4   auth: auth.yml
5 
6 auth: OAuthScheme
7 auth-schemes:
8   OAuthScheme:
9     scheme: oauth
10     type: client-credentials
11     client-id-env: YOUR_CLIENT_ID
12     client-secret-env: YOUR_CLIENT_SECRET
13     get-token:
14       endpoint: auth.getTokenWithClientCredentials
15       request-properties:
16         client-id: $request.client_id         # 格式：参数名: $request.属性名
17         client-secret: $request.client_secret # 格式：参数名: $request.属性名            
18       response-properties:
19         access-token: $response.access_token  # 格式：参数名: $response.属性名
20         expires-in: $response.expires_in      # 格式：参数名: $response.属性名

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

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

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

auth.yml

1 types:
2   TokenResponse:
3     docs: |
4       OAuth 令牌响应。
5     properties:
6       access_token: string
7       expires_in: integer
8       refresh_token: optional<string>
9 
10 service:
11   auth: false
12   base-path: /
13   endpoints:
14     getTokenWithClientCredentials:
15       path: /token
16       method: POST
17       request:
18         name: GetTokenRequest
19         body:
20           properties:
21             client_id: string
22             client_secret: string
23             audience: literal<"https://api.example.com">
24             grant_type: literal<"client_credentials">
25             scope: optional<string>
26       response: TokenResponse

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

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

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

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

api.yml

1 auth-schemes:
2   OAuthScheme:
3     scheme: oauth
4     type: client-credentials
5     token-header: Fern-Authorization
6     token-prefix: Fern-Bearer
7     get-token:
8       ...

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

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

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

api.yml

1 auth-schemes:
2   AuthScheme:                     
3     ...

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

api.yml

1 auth: AuthScheme                  
2 auth-schemes:
3   AuthScheme:                     
4     ...

Bearer 身份验证

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

api.yml

1 auth: Bearer                  
2 auth-schemes:
3   Bearer:                     
4     scheme: bearer

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

index.ts

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

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

api.yml

1 auth: Bearer                  
2 auth-schemes:
3   Bearer:                     
4     scheme: bearer
5     token:
6       name: apiKey 
7       env: PLANTSTORE_API_KEY

生成的 SDK 将如下所示：

index.ts

1 // 使用 process.env.PLANTSTORE_API_KEY
2 let client = new Client(); 
3 
4 // token 已重命名为 apiKey
5 client = new Client({
6   apiKey: "ey34..."
7 })

基本身份验证

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

api.yml

1 auth: Basic                  
2 auth-schemes:
3   Basic:                     
4     scheme: basic

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

index.ts

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

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

api.yml

1 auth: Basic                  
2 auth-schemes:
3   Basic:                     
4     scheme: basic
5     username:
6       name: clientId
7       env: PLANTSTORE_CLIENT_ID
8     password:
9       name: clientSecret
10       env: PLANTSTORE_CLIENT_SECRET

生成的 SDK 将如下所示：

index.ts

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

自定义标头（例如 API key）

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

api.yml

1 auth: ApiKeyAuthScheme
2 auth-schemes:
3   ApiKeyAuthScheme:
4     header: X-API-Key
5     type: string

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

index.ts

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

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

api.yml

1 auth: ApiKeyAuthScheme
2 auth-schemes:
3   ApiKeyAuthScheme:
4     header: X-API-Key
5     type: string
6     name: apiKey
7     env: PLANTSTORE_API_KEY

生成的 SDK 将如下所示：

index.ts

1 // 使用 process.env.PLANTSTORE_API_KEY
2 let client = new Client(); 
3 
4 // 参数已重命名
5 client = new Client({
6   apiKey: "ey34..."
7 })

OAuth 客户端凭据

团队版和企业版功能

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

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

api.yml

1 name: api
2 
3 imports:
4   auth: auth.yml
5 
6 auth: OAuthScheme
7 auth-schemes:
8   OAuthScheme:
9     scheme: oauth
10     type: client-credentials
11     client-id-env: YOUR_CLIENT_ID
12     client-secret-env: YOUR_CLIENT_SECRET
13     get-token:
14       endpoint: auth.getTokenWithClientCredentials
15       request-properties:
16         client-id: $request.client_id         # 格式：参数名: $request.属性名
17         client-secret: $request.client_secret # 格式：参数名: $request.属性名            
18       response-properties:
19         access-token: $response.access_token  # 格式：参数名: $response.属性名
20         expires-in: $response.expires_in      # 格式：参数名: $response.属性名

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

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

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

auth.yml

1 types:
2   TokenResponse:
3     docs: |
4       OAuth 令牌响应。
5     properties:
6       access_token: string
7       expires_in: integer
8       refresh_token: optional<string>
9 
10 service:
11   auth: false
12   base-path: /
13   endpoints:
14     getTokenWithClientCredentials:
15       path: /token
16       method: POST
17       request:
18         name: GetTokenRequest
19         body:
20           properties:
21             client_id: string
22             client_secret: string
23             audience: literal<"https://api.example.com">
24             grant_type: literal<"client_credentials">
25             scope: optional<string>
26       response: TokenResponse

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

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

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

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

api.yml

1 auth-schemes:
2   OAuthScheme:
3     scheme: oauth
4     type: client-credentials
5     token-header: Fern-Authorization
6     token-prefix: Fern-Bearer
7     get-token:
8       ...

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

1	auth: Bearer
2	auth-schemes:
3	Bearer:
4	scheme: bearer
5	token:
6	name: apiKey
7	env: PLANTSTORE_API_KEY

1	// 使用 process.env.PLANTSTORE_API_KEY
2	let client = new Client();
3
4	// token 已重命名为 apiKey
5	client = new Client({
6	apiKey: "ey34..."
7	})

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

1	auth: Basic
2	auth-schemes:
3	Basic:
4	scheme: basic
5	username:
6	name: clientId
7	env: PLANTSTORE_CLIENT_ID
8	password:
9	name: clientSecret
10	env: PLANTSTORE_CLIENT_SECRET

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

1	auth: ApiKeyAuthScheme
2	auth-schemes:
3	ApiKeyAuthScheme:
4	header: X-API-Key
5	type: string

1	name: api
2
3	imports:
4	auth: auth.yml
5
6	auth: OAuthScheme
7	auth-schemes:
8	OAuthScheme:
9	scheme: oauth
10	type: client-credentials
11	client-id-env: YOUR_CLIENT_ID
12	client-secret-env: YOUR_CLIENT_SECRET
13	get-token:
14	endpoint: auth.getTokenWithClientCredentials
15	request-properties:
16	client-id: $request.client_id # 格式：参数名: $request.属性名
17	client-secret: $request.client_secret # 格式：参数名: $request.属性名
18	response-properties:
19	access-token: $response.access_token # 格式：参数名: $response.属性名
20	expires-in: $response.expires_in # 格式：参数名: $response.属性名

1	types:
2	TokenResponse:
3	docs: \|
4	OAuth 令牌响应。
5	properties:
6	access_token: string
7	expires_in: integer
8	refresh_token: optional<string>
9
10	service:
11	auth: false
12	base-path: /
13	endpoints:
14	getTokenWithClientCredentials:
15	path: /token
16	method: POST
17	request:
18	name: GetTokenRequest
19	body:
20	properties:
21	client_id: string
22	client_secret: string
23	audience: literal<"https://api.example.com">
24	grant_type: literal<"client_credentials">
25	scope: optional<string>
26	response: TokenResponse