You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: fern/products/api-def/openapi-pages/auth.mdx
+62-7Lines changed: 62 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,7 @@
1
1
---
2
2
title: Authentication
3
-
subtitle: Model auth schemes such as bearer, basic, and api key.
3
+
description: Model auth schemes such as bearer, basic, api key, and OAuth.
4
+
max-toc-depth: 2
4
5
---
5
6
6
7
Configuring authentication schemes happens in the `components.securitySchemes` section of OpenAPI. All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials.
@@ -181,6 +182,60 @@ client = new Client({
181
182
})
182
183
```
183
184
185
+
## OAuth client credentials
186
+
187
+
<Markdown src="/snippets/pro-plan.mdx" />
188
+
189
+
Configure OAuth 2.0 using client credentials in `generators.yml`:
190
+
191
+
```yaml title="generators.yml" maxLines=10
192
+
auth-schemes:
193
+
OAuth:
194
+
scheme: oauth
195
+
type: client-credentials
196
+
client-id-env: "OAUTH_CLIENT_ID"
197
+
client-secret-env: "OAUTH_CLIENT_SECRET"
198
+
get-token:
199
+
endpoint: "POST /oauth/token"
200
+
request-properties:
201
+
client-id: "client_id"
202
+
client-secret: "client_secret"
203
+
response-properties:
204
+
access-token: "access_token"
205
+
expires-in: "expires_in"
206
+
refresh-token: "refresh_token"
207
+
refresh-token:
208
+
endpoint: "POST /oauth/refresh"
209
+
request-properties:
210
+
refresh-token: "refresh_token"
211
+
response-properties:
212
+
access-token: "access_token"
213
+
expires-in: "expires_in"
214
+
api:
215
+
auth: OAuth
216
+
```
217
+
218
+
<Info title="Endpoint configuration and token refresh">
219
+
The `endpoint` values (e.g., `"POST /oauth/token"`) reference paths defined in your OpenAPI specification. When `expires-in` is returned, the SDK will automatically refresh tokens before they expire. For more details on OAuth configuration options, see the [Auth scheme reference](#oauth-authentication) below.
220
+
</Info>
221
+
222
+
The generated SDK would look like:
223
+
224
+
```ts index.ts
225
+
226
+
// Uses process.env.OAUTH_CLIENT_ID and process.env.OAUTH_CLIENT_SECRET
227
+
let client = new Client();
228
+
229
+
// Or provide credentials explicitly
230
+
client = new Client({
231
+
clientId: "your_client_id",
232
+
clientSecret: "your_client_secret"
233
+
})
234
+
235
+
// All token management happens automatically
236
+
await client.users.list();
237
+
```
238
+
184
239
## Multiple security schemes
185
240
186
241
If you would like to define multiple security schemes, simply
@@ -201,11 +256,11 @@ components:
201
256
202
257
## Override security scheme
203
258
204
-
You can use `generators.yml` to define custom authentication schemes that will take precedence when generating SDKs.
259
+
You can use `generators.yml` to define custom authentication schemes that will take precedence when generating SDKs. This is also how OAuth authentication is configured for OpenAPI specs.
205
260
206
261
First, use the `auth-schemes` property to define your authentication scheme. Then, specify your auth scheme in the `api` property to override your OpenAPI spec.
Specifies the endpoint that exchanges client credentials for an access token. This endpoint is called automatically when the SDK client is initialized.
Customizes the property names used in the token request.
18
+
Maps OAuth parameter names to your API's request field names. Use this when your token endpoint expects different field names than the OAuth standard (e.g., your API uses `clientId` instead of `client_id`).
Maps custom property names in your OAuth token response (e.g., if your API returns `accessToken` instead of `access_token`).
30
+
Maps your API's response field names to OAuth standard names. Use this when your API returns tokens with different field names (e.g., `accessToken` instead of `access_token`).
The response field name for token expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). When present, the SDK automatically refreshes tokens before expiration.
For Fern Definition, you can configure OAuth authentication either in `generators.yml` or [directly in your `api.yml` file](/api-definitions/ferndef/authentication#oauth-client-credentials). For OpenAPI, [OAuth must be configured in `generators.yml`](/api-definitions/openapi/authentication#oauth-client-credentials).
3
+
</Note>
2
4
3
-
```yaml
5
+
Configure OAuth 2.0 client credentials authentication. Optionally configure a `refresh-token` endpoint for token renewal without re-authentication.
Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization.
@@ -48,8 +51,8 @@ auth-schemes:
48
51
Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization.
Prefix added to the access token in the Authorization header (e.g., `"Bearer"` results in `"Authorization: Bearer <token>"`). Useful when your API expects a custom format.
HTTP header name used to send the access token. Defaults to `"Authorization"` but can be customized if your API uses a different header (e.g., `"X-API-Token"`).
Specifies the endpoint that exchanges a refresh token for a new access token. When configured, the SDK automatically uses this endpoint to renew expired tokens without re-sending credentials. If not configured, the SDK will re-authenticate using `get-token` when tokens expire.
0 commit comments