Skip to content

Commit 0cc3f6e

Browse files
devalogdevalog
authored
Expand auth-schemes section in generators.yml reference (#331)
1 parent 90b500c commit 0cc3f6e

File tree

1 file changed

+265
-2
lines changed

1 file changed

+265
-2
lines changed

‎fern/products/sdks/reference/generators-yml-reference.mdx‎

Lines changed: 265 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,272 @@ groups:
5757
```
5858
5959
## auth-schemes
60-
Configures authentication methods for your API.
60+
Define authentication methods for your API. Create named authentication schemes that your endpoints can reference.
6161
62-
<ParamField path="auth-schemes" type="map<string, AuthSchemeDeclarationSchema>" required={false} toc={true}>
62+
Choose from OAuth 2.0, custom headers (API keys), HTTP Basic, or Bearer token authentication.
63+
64+
```yaml
65+
auth-schemes:
66+
# User-defined scheme name - OAuth with minimal configuration
67+
simple-oauth:
68+
scheme: oauth
69+
type: client-credentials
70+
get-token:
71+
endpoint: "auth.token"
72+
73+
# User-defined scheme name - Header auth with custom configuration
74+
custom-header:
75+
name: "Custom Auth"
76+
header: "X-Custom-Auth"
77+
prefix: "Custom "
78+
env: "CUSTOM_TOKEN"
79+
80+
# User-defined scheme name - Basic auth
81+
http-basic:
82+
scheme: basic
83+
84+
# User-defined scheme name - Bearer token
85+
jwt-bearer:
86+
scheme: bearer
87+
```
88+
89+
### OAuth Authentication
90+
91+
Configure OAuth 2.0 client credentials authentication.
92+
93+
```yaml
94+
auth-schemes:
95+
my-oauth: # User-defined scheme name
96+
scheme: oauth
97+
type: client-credentials
98+
scopes:
99+
- "read:users"
100+
- "write:users"
101+
client-id-env: "OAUTH_CLIENT_ID"
102+
client-secret-env: "OAUTH_CLIENT_SECRET"
103+
token-prefix: "Bearer"
104+
token-header: "Authorization"
105+
get-token:
106+
endpoint: "auth.get_token"
107+
request-properties:
108+
client-id: "clientId"
109+
client-secret: "clientSecret"
110+
scopes: "scope"
111+
response-properties:
112+
access-token: "access_token"
113+
expires-in: "expires_in"
114+
refresh-token: "refresh_token"
115+
refresh-token:
116+
endpoint: "auth.refresh_token"
117+
request-properties:
118+
refresh-token: "refreshToken"
119+
response-properties:
120+
access-token: "access_token"
121+
expires-in: "expires_in"
122+
refresh-token: "refresh_token"
123+
```
124+
125+
<ParamField path="scheme" type="'oauth'" required={true}>
126+
Must be set to `"oauth"` for OAuth authentication schemes.
127+
</ParamField>
128+
<ParamField path="type" type="literal<'client-credentials'>" required={true}>
129+
The OAuth flow type. Currently only `"client-credentials"` is supported.
130+
</ParamField>
131+
<ParamField path="scopes" type="list<string>" required={false}>
132+
List of OAuth scopes to request during authentication.
133+
</ParamField>
134+
<ParamField path="client-id-env" type="string" required={false}>
135+
Environment variable name containing the OAuth client ID.
136+
</ParamField>
137+
<ParamField path="client-secret-env" type="string" required={false}>
138+
Environment variable name containing the OAuth client secret.
139+
</ParamField>
140+
<ParamField path="token-prefix" type="string" default="Bearer">
141+
Sets the token header value prefix.
142+
</ParamField>
143+
<ParamField path="token-header" type="string" default="Authorization">
144+
Sets the token header key name.
145+
</ParamField>
146+
147+
#### get-token
148+
149+
Configuration for the token acquisition endpoint.
150+
151+
```yaml
152+
auth-schemes:
153+
my-oauth:
154+
scheme: oauth
155+
# ... other OAuth config
156+
get-token:
157+
endpoint: "auth.get_token"
158+
request-properties:
159+
client-id: "clientId"
160+
client-secret: "clientSecret"
161+
response-properties:
162+
access-token: "access_token"
163+
expires-in: "expires_in"
164+
```
165+
166+
<ParamField path="endpoint" type="string" required={true}>
167+
The endpoint to get the access token, such as `'auth.get_token'`.
168+
</ParamField>
169+
<ParamField path="request-properties" type="object" required={false}>
170+
Customizes the property names used in the token request.
171+
</ParamField>
172+
<ParamField path="client-id" type="string" required={false}>
173+
The property name for the client ID in the request.
174+
</ParamField>
175+
<ParamField path="client-secret" type="string" required={false}>
176+
The property name for the client secret in the request.
177+
</ParamField>
178+
<ParamField path="scopes" type="string" required={false}>
179+
The property name for the scopes in the request.
180+
</ParamField>
181+
<ParamField path="response-properties" type="object" required={false}>
182+
Maps custom property names in your OAuth token response (e.g., if your API returns `accessToken` instead of `access_token`).
183+
</ParamField>
184+
<ParamField path="access-token" type="string" required={false}>
185+
The property name for the access token in the response.
186+
</ParamField>
187+
<ParamField path="expires-in" type="string" required={false}>
188+
The property name for the expires in property in the response.
189+
</ParamField>
190+
<ParamField path="refresh-token" type="string" required={false}>
191+
The property name for the refresh token in the response.
192+
</ParamField>
193+
194+
#### refresh-token
195+
196+
Configuration for the token refresh endpoint.
197+
198+
```yaml
199+
auth-schemes:
200+
my-oauth:
201+
scheme: oauth
202+
# ... other OAuth config
203+
refresh-token:
204+
endpoint: "auth.refresh_token"
205+
request-properties:
206+
refresh-token: "refreshToken"
207+
response-properties:
208+
access-token: "access_token"
209+
expires-in: "expires_in"
210+
```
211+
212+
<ParamField path="endpoint" type="string" required={true}>
213+
The endpoint to refresh the access token, such as `'auth.refresh_token'`.
214+
</ParamField>
215+
<ParamField path="request-properties" type="object" required={false}>
216+
Maps custom property names in your refresh token request.
217+
</ParamField>
218+
<ParamField path="refresh-token" type="string" required={true}>
219+
The property name for the refresh token in the request.
220+
</ParamField>
221+
<ParamField path="response-properties" type="object" required={false}>
222+
Maps custom property names in your refresh token response.
223+
</ParamField>
224+
<ParamField path="access-token" type="string" required={false}>
225+
The property name for the access token in the response.
226+
</ParamField>
227+
<ParamField path="expires-in" type="string" required={false}>
228+
The property name for the expires in property in the response.
229+
</ParamField>
230+
<ParamField path="refresh-token" type="string" required={false}>
231+
The property name for the refresh token in the response.
232+
</ParamField>
233+
234+
### Header Authentication
235+
236+
Configure authentication using custom HTTP headers, such as API keys or tokens.
237+
238+
```yaml
239+
auth-schemes:
240+
api-key: # User-defined scheme name
241+
name: "API Key Authentication"
242+
header: "X-API-Key"
243+
type: "string"
244+
prefix: "ApiKey "
245+
env: "MY_API_KEY"
246+
```
247+
248+
<ParamField path="header" type="string" required={true}>
249+
The name of the HTTP header to use for authentication.
250+
</ParamField>
251+
<ParamField path="name" type="string" required={false}>
252+
A descriptive name for this authentication scheme.
253+
</ParamField>
254+
<ParamField path="type" type="string" default="string">
255+
The type of the header value.
256+
</ParamField>
257+
<ParamField path="prefix" type="string" required={false}>
258+
A prefix to prepend to the header value (e.g., `"Bearer "` or `"Token "`).
259+
</ParamField>
260+
<ParamField path="env" type="string" required={false}>
261+
Environment variable name containing the authentication value.
262+
</ParamField>
263+
264+
### Basic Authentication
265+
266+
Configure HTTP Basic authentication using username and password credentials.
267+
268+
```yaml
269+
auth-schemes:
270+
basic-auth: # User-defined scheme name
271+
scheme: basic
272+
username:
273+
name: "Username"
274+
env: "BASIC_AUTH_USERNAME"
275+
password:
276+
name: "Password"
277+
env: "BASIC_AUTH_PASSWORD"
278+
```
279+
280+
<ParamField path="scheme" type="'basic'" required={true}>
281+
Must be set to `"basic"` for Basic authentication schemes.
282+
</ParamField>
283+
<ParamField path="username" type="object" required={false}>
284+
Configuration for the username credential.
285+
</ParamField>
286+
<ParamField path="name" type="string" required={false}>
287+
A descriptive name for the username.
288+
</ParamField>
289+
<ParamField path="env" type="string" required={false}>
290+
Environment variable name containing the username.
291+
</ParamField>
292+
<ParamField path="password" type="object" required={false}>
293+
Configuration for the password credential.
294+
</ParamField>
295+
<ParamField path="name" type="string" required={false}>
296+
A descriptive name for the password.
297+
</ParamField>
298+
<ParamField path="env" type="string" required={false}>
299+
Environment variable name containing the password.
300+
</ParamField>
301+
302+
### Bearer Token Authentication
303+
304+
Configure Bearer token authentication for API access.
305+
306+
```yaml
307+
auth-schemes:
308+
bearer-token: # User-defined scheme name
309+
scheme: bearer
310+
token:
311+
name: "Access Token"
312+
env: "BEARER_TOKEN"
313+
```
314+
315+
<ParamField path="scheme" type="'bearer'" required={true}>
316+
Must be set to `"bearer"` for Bearer token authentication schemes.
317+
</ParamField>
318+
<ParamField path="token" type="object" required={false}>
319+
Configuration for the bearer token.
320+
</ParamField>
321+
<ParamField path="token.name" type="string" required={false}>
322+
A descriptive name for the token.
323+
</ParamField>
324+
<ParamField path="token.env" type="string" required={false}>
325+
Environment variable name containing the bearer token.
63326
</ParamField>
64327

65328
## api

0 commit comments

Comments
 (0)