diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index ce3b22b7a..f2cfa9fbc 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -57,9 +57,272 @@ groups: ``` ## auth-schemes -Configures authentication methods for your API. +Define authentication methods for your API. Create named authentication schemes that your endpoints can reference. - +Choose from OAuth 2.0, custom headers (API keys), HTTP Basic, or Bearer token authentication. + +```yaml +auth-schemes: + # User-defined scheme name - OAuth with minimal configuration + simple-oauth: + scheme: oauth + type: client-credentials + get-token: + endpoint: "auth.token" + + # User-defined scheme name - Header auth with custom configuration + custom-header: + name: "Custom Auth" + header: "X-Custom-Auth" + prefix: "Custom " + env: "CUSTOM_TOKEN" + + # User-defined scheme name - Basic auth + http-basic: + scheme: basic + + # User-defined scheme name - Bearer token + jwt-bearer: + scheme: bearer +``` + +### OAuth Authentication + +Configure OAuth 2.0 client credentials authentication. + +```yaml +auth-schemes: + my-oauth: # User-defined scheme name + scheme: oauth + type: client-credentials + scopes: + - "read:users" + - "write:users" + client-id-env: "OAUTH_CLIENT_ID" + client-secret-env: "OAUTH_CLIENT_SECRET" + token-prefix: "Bearer" + token-header: "Authorization" + get-token: + endpoint: "auth.get_token" + request-properties: + client-id: "clientId" + client-secret: "clientSecret" + scopes: "scope" + response-properties: + access-token: "access_token" + expires-in: "expires_in" + refresh-token: "refresh_token" + refresh-token: + endpoint: "auth.refresh_token" + request-properties: + refresh-token: "refreshToken" + response-properties: + access-token: "access_token" + expires-in: "expires_in" + refresh-token: "refresh_token" +``` + + + Must be set to `"oauth"` for OAuth authentication schemes. + + + The OAuth flow type. Currently only `"client-credentials"` is supported. + + + List of OAuth scopes to request during authentication. + + + Environment variable name containing the OAuth client ID. + + + Environment variable name containing the OAuth client secret. + + + Sets the token header value prefix. + + + Sets the token header key name. + + +#### get-token + +Configuration for the token acquisition endpoint. + +```yaml +auth-schemes: + my-oauth: + scheme: oauth + # ... other OAuth config + get-token: + endpoint: "auth.get_token" + request-properties: + client-id: "clientId" + client-secret: "clientSecret" + response-properties: + access-token: "access_token" + expires-in: "expires_in" +``` + + + The endpoint to get the access token, such as `'auth.get_token'`. + + + Customizes the property names used in the token request. + + + The property name for the client ID in the request. + + + The property name for the client secret in the request. + + + The property name for the scopes in the request. + + + Maps custom property names in your OAuth token response (e.g., if your API returns `accessToken` instead of `access_token`). + + + The property name for the access token in the response. + + + The property name for the expires in property in the response. + + + The property name for the refresh token in the response. + + +#### refresh-token + +Configuration for the token refresh endpoint. + +```yaml +auth-schemes: + my-oauth: + scheme: oauth + # ... other OAuth config + refresh-token: + endpoint: "auth.refresh_token" + request-properties: + refresh-token: "refreshToken" + response-properties: + access-token: "access_token" + expires-in: "expires_in" +``` + + + The endpoint to refresh the access token, such as `'auth.refresh_token'`. + + + Maps custom property names in your refresh token request. + + + The property name for the refresh token in the request. + + + Maps custom property names in your refresh token response. + + + The property name for the access token in the response. + + + The property name for the expires in property in the response. + + + The property name for the refresh token in the response. + + +### Header Authentication + +Configure authentication using custom HTTP headers, such as API keys or tokens. + +```yaml +auth-schemes: + api-key: # User-defined scheme name + name: "API Key Authentication" + header: "X-API-Key" + type: "string" + prefix: "ApiKey " + env: "MY_API_KEY" +``` + + + The name of the HTTP header to use for authentication. + + + A descriptive name for this authentication scheme. + + + The type of the header value. + + + A prefix to prepend to the header value (e.g., `"Bearer "` or `"Token "`). + + + Environment variable name containing the authentication value. + + +### Basic Authentication + +Configure HTTP Basic authentication using username and password credentials. + +```yaml +auth-schemes: + basic-auth: # User-defined scheme name + scheme: basic + username: + name: "Username" + env: "BASIC_AUTH_USERNAME" + password: + name: "Password" + env: "BASIC_AUTH_PASSWORD" +``` + + + Must be set to `"basic"` for Basic authentication schemes. + + + Configuration for the username credential. + + + A descriptive name for the username. + + + Environment variable name containing the username. + + + Configuration for the password credential. + + + A descriptive name for the password. + + + Environment variable name containing the password. + + +### Bearer Token Authentication + +Configure Bearer token authentication for API access. + +```yaml +auth-schemes: + bearer-token: # User-defined scheme name + scheme: bearer + token: + name: "Access Token" + env: "BEARER_TOKEN" +``` + + + Must be set to `"bearer"` for Bearer token authentication schemes. + + + Configuration for the bearer token. + + + A descriptive name for the token. + + + Environment variable name containing the bearer token. ## api