Skip to content

Commit 23b6302

Browse files
devalogdevalog
authored
Flesh out groups.generators[].api.auth section of generators.yml reference page (#212)
1 parent d0a8b14 commit 23b6302

File tree

1 file changed

+229
-2
lines changed

1 file changed

+229
-2
lines changed

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

Lines changed: 229 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -840,11 +840,238 @@ The path to the generated snippets file.
840840

841841
### API Settings Override
842842

843-
<ParamField path="groups.{groupName}.generators[].api.auth" type="ApiAuthSchema" required={false} toc={true}>
843+
Override authentication settings in your API spec using the `api` configuration.
844+
You can specify authentication schemes, reference existing auth configurations,
845+
and set additional API-specific settings.
846+
847+
#### String Reference
848+
849+
Reference a pre-defined authentication scheme by name.
850+
851+
```yml {6-7}
852+
groups:
853+
ts-sdk:
854+
generators:
855+
- name: fernapi/fern-typescript-sdk
856+
...
857+
api:
858+
auth: "bearer-token"
859+
```
860+
861+
<ParamField path="auth" type="string" required={false} toc={true}>
862+
The name of an authentication scheme defined in your API specification.
863+
</ParamField>
864+
865+
#### Scheme Reference
866+
867+
Reference a specific authentication scheme with optional documentation.
868+
869+
```yml {6-9}
870+
groups:
871+
ts-sdk:
872+
generators:
873+
- name: fernapi/fern-typescript-sdk
874+
...
875+
api:
876+
auth:
877+
scheme: "my-auth-scheme"
878+
docs: "Custom authentication method"
879+
```
880+
881+
<ParamField path="scheme" type="string" required={true} toc={true}>
882+
The name of the authentication scheme to use.
883+
</ParamField>
884+
885+
<ParamField path="docs" type="string" required={false} toc={true}>
886+
Documentation describing this authentication configuration.
887+
</ParamField>
888+
889+
#### Multiple Authentication Options
890+
891+
Allow any of multiple authentication schemes to be used.
892+
893+
```yml {6-12}
894+
groups:
895+
ts-sdk:
896+
generators:
897+
- name: fernapi/fern-typescript-sdk
898+
...
899+
api:
900+
auth:
901+
any:
902+
- "api-key"
903+
- "bearer-token"
904+
- scheme: "oauth-flow"
905+
docs: "Supports multiple authentication methods"
906+
```
907+
908+
<ParamField path="any" type="list<string | { scheme: string }>" required={true} toc={true}>
909+
List of authentication schemes where any one can be used. Can include string references or scheme objects.
910+
</ParamField>
911+
912+
<ParamField path="docs" type="string" required={false} toc={true}>
913+
Documentation describing this authentication configuration.
914+
</ParamField>
915+
916+
#### Custom Authentication Schemes
917+
918+
Define a custom authentication schemes using `auth-schemes`. You define a name for your custom scheme, and then specify the authentication method (`header`, `basic`, `bearer`, or `oauth`).
919+
920+
<AccordionGroup>
921+
<Accordion title="Header authentication">
922+
923+
Send authentication tokens or API keys in custom HTTP headers.
924+
925+
```yml {8-12}
926+
groups:
927+
ts-sdk:
928+
generators:
929+
- name: fernapi/fern-typescript-sdk
930+
...
931+
api:
932+
auth-schemes:
933+
api-key: # User-defined name for your auth schema
934+
header: "X-API-Key"
935+
type: "string"
936+
prefix: "Bearer "
937+
env: "API_KEY"
938+
```
939+
940+
<ParamField path="header" type="string" required={true} toc={true}>
941+
The name of the header to send the authentication value in.
942+
</ParamField>
943+
944+
<ParamField path="type" type="string" required={false} toc={true}>
945+
The type of the authentication value. Defaults to "string".
946+
</ParamField>
947+
948+
<ParamField path="prefix" type="string" required={false} toc={true}>
949+
A prefix to add before the authentication value in the header.
950+
</ParamField>
951+
952+
<ParamField path="env" type="string" required={false} toc={true}>
953+
Environment variable name to read the authentication value from.
954+
</ParamField>
955+
</Accordion>
956+
957+
<Accordion title="Basic authentication">
958+
959+
Standard HTTP basic authentication using username and password credentials.
960+
961+
```yaml {8-15}
962+
groups:
963+
ts-sdk:
964+
generators:
965+
- name: fernapi/fern-typescript-sdk
966+
...
967+
api:
968+
auth-schemes:
969+
basic-auth: # User-defined name for your auth schema
970+
scheme: "basic"
971+
username:
972+
name: "username"
973+
env: "AUTH_USERNAME"
974+
password:
975+
name: "password"
976+
env: "AUTH_PASSWORD"
977+
```
978+
<ParamField path="scheme" type="'basic'" required={true} toc={true}>
979+
Must be set to "basic" for basic authentication.
980+
</ParamField>
981+
982+
<ParamField path="username" type="{ name: string, env?: string }" required={false} toc={true}>
983+
Configuration for the username field.
984+
</ParamField>
985+
986+
<ParamField path="password" type="{ name: string, env?: string }" required={false} toc={true}>
987+
Configuration for the password field.
988+
</ParamField>
989+
</Accordion>
990+
991+
<Accordion title="Bearer Token Authentication">
992+
993+
Authentication using bearer tokens in the Authorization header.
994+
995+
```yml {8-12}
996+
groups:
997+
ts-sdk:
998+
generators:
999+
- name: fernapi/fern-typescript-sdk
1000+
...
1001+
api:
1002+
auth-schemes:
1003+
bearer: # User-defined name for your auth schema
1004+
scheme: "bearer"
1005+
token:
1006+
name: "token"
1007+
env: "BEARER_TOKEN"
1008+
```
1009+
1010+
<ParamField path="scheme" type="'bearer'" required={true} toc={true}>
1011+
Must be set to "bearer" for bearer token authentication.
1012+
</ParamField>
1013+
1014+
<ParamField path="token" type="{ name: string, env?: string }" required={false} toc={true}>
1015+
Configuration for the bearer token.
1016+
</ParamField>
1017+
</Accordion>
1018+
1019+
<Accordion title="OAuth Client Credentials">
1020+
1021+
OAuth 2.0 client credentials flow for machine-to-machine authentication.
1022+
1023+
```yml {8-12}
1024+
groups:
1025+
ts-sdk:
1026+
generators:
1027+
- name: fernapi/fern-typescript-sdk
1028+
...
1029+
api:
1030+
auth-schemes:
1031+
oauth: # User-defined name for your auth schema
1032+
scheme: "oauth"
1033+
type: "client-credentials"
1034+
get-token:
1035+
endpoint: "auth.get_token"
1036+
```
1037+
1038+
<ParamField path="scheme" type="'oauth'" required={true} toc={true}>
1039+
Must be set to "oauth" for OAuth authentication.
1040+
</ParamField>
1041+
1042+
<ParamField path="type" type="'client-credentials'" required={true} toc={true}>
1043+
Must be set to "client-credentials" for OAuth client credentials flow.
1044+
</ParamField>
1045+
1046+
<ParamField path="scopes" type="list<string>" required={false} toc={true}>
1047+
List of OAuth scopes to request.
1048+
</ParamField>
1049+
1050+
<ParamField path="client-id-env" type="string" required={false} toc={true}>
1051+
Environment variable name for the OAuth client ID.
1052+
</ParamField>
1053+
1054+
<ParamField path="client-secret-env" type="string" required={false} toc={true}>
1055+
Environment variable name for the OAuth client secret.
1056+
</ParamField>
1057+
1058+
<ParamField path="token-prefix" type="string" required={false} toc={true}>
1059+
Sets the token header value prefix. Defaults to 'Bearer'.
1060+
</ParamField>
1061+
1062+
<ParamField path="token-header" type="string" required={false} toc={true}>
1063+
Sets the token header key name. Defaults to 'Authorization'.
1064+
</ParamField>
1065+
1066+
<ParamField path="get-token" type="{ endpoint: string, request-properties?: object, response-properties?: object }" required={true} toc={true}>
1067+
Configuration for the token endpoint to get access tokens.
8441068
</ParamField>
8451069

846-
<ParamField path="groups.{groupName}.generators[].api.settings" type="APIDefinitionSettingsSchema" required={false} toc={true}>
1070+
<ParamField path="refresh-token" type="{ endpoint: string, request-properties?: object, response-properties?: object }" required={false} toc={true}>
1071+
Configuration for the refresh token endpoint.
8471072
</ParamField>
1073+
</Accordion>
1074+
</AccordionGroup>
8481075

8491076
## reviewers
8501077
Who should review generated code.

0 commit comments

Comments
 (0)