diff --git a/fern/products/api-def/openapi-pages/auth.mdx b/fern/products/api-def/openapi-pages/auth.mdx index 22af42aec..2eaa1e75e 100644 --- a/fern/products/api-def/openapi-pages/auth.mdx +++ b/fern/products/api-def/openapi-pages/auth.mdx @@ -1,6 +1,7 @@ --- title: Authentication -subtitle: Model auth schemes such as bearer, basic, and api key. +description: Model auth schemes such as bearer, basic, api key, and OAuth. +max-toc-depth: 2 --- 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,31 +182,67 @@ client = new Client({ }) ``` -## Multiple security schemes +## OAuth client credentials + + + +Configure OAuth 2.0 client credentials in `generators.yml` rather than in the API specification: + +```yaml title="generators.yml" maxLines=10 +auth-schemes: + OAuth: + scheme: oauth + type: client-credentials + client-id-env: "OAUTH_CLIENT_ID" + client-secret-env: "OAUTH_CLIENT_SECRET" + get-token: + endpoint: "POST /oauth/token" + request-properties: + client-id: "client_id" + client-secret: "client_secret" + response-properties: + access-token: "access_token" + expires-in: "expires_in" + refresh-token: "refresh_token" + refresh-token: + endpoint: "POST /oauth/refresh" + request-properties: + refresh-token: "refresh_token" + response-properties: + access-token: "access_token" + expires-in: "expires_in" +api: + auth: OAuth +``` -If you would like to define multiple security schemes, simply -list them under `components.securitySchemes`. For example, if you wanted to support -`basic` and `apiKey` security schemes, see the example below: + +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. + -```yaml title="openapi.yml" {3,6} -components: - securitySchemes: - BearerAuth: - type: http - scheme: bearer - ApiKey: - type: apiKey - in: header - name: X_API_KEY +The generated SDK would look like: + +```ts index.ts + +// Uses process.env.OAUTH_CLIENT_ID and process.env.OAUTH_CLIENT_SECRET +let client = new Client(); + +// Or provide credentials explicitly +client = new Client({ + clientId: "your_client_id", + clientSecret: "your_client_secret" +}) + +// All token management happens automatically +await client.users.list(); ``` ## Override security scheme -You can use `generators.yml` to define custom authentication schemes that will take precedence when generating SDKs. +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. 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. -```yml title="generators.yml" {1-6, 8} +```yml title="generators.yml" auth-schemes: # Define custom auth scheme Bearer: scheme: bearer @@ -219,16 +256,16 @@ api: ### Auth scheme reference - + - + - + - + #### get-token diff --git a/fern/products/sdks/capabilities.mdx b/fern/products/sdks/capabilities.mdx index 776cb3ac5..072fab226 100644 --- a/fern/products/sdks/capabilities.mdx +++ b/fern/products/sdks/capabilities.mdx @@ -93,7 +93,7 @@ layout: overview - + Fern supports OAuth as a first class citizen

diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 7bfa46d98..378b49702 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -57,9 +57,13 @@ groups: ## `auth-schemes` -Define authentication methods for your API that your endpoints can reference. Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication. +Define authentication methods for your API that your endpoints can reference. Authentication schemes defined in `generators.yml` take precedence over authentication schemes defined in your spec. -Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings). +Choose from custom headers (API keys), HTTP Basic, Bearer token, or OAuth 2.0 authentication. + + + Alternatively, you can [define authentication for individual SDKs](#override-api-authentication-settings). + ```yaml title="generators.yml" maxLines=10 auth-schemes: @@ -95,7 +99,7 @@ auth-schemes: - + #### `get-token` diff --git a/fern/products/sdks/snippets/oauth-get-token.mdx b/fern/products/sdks/snippets/oauth-get-token.mdx index 938bf9569..b739cedcd 100644 --- a/fern/products/sdks/snippets/oauth-get-token.mdx +++ b/fern/products/sdks/snippets/oauth-get-token.mdx @@ -1,6 +1,6 @@ -Configuration for the token acquisition endpoint. +Specifies the endpoint that exchanges client credentials for an access token. This endpoint is called automatically when the SDK client is initialized. -```yaml +```yaml title="generators.yml" get-token: endpoint: "auth.get_token" request-properties: @@ -12,29 +12,29 @@ get-token: ``` - The endpoint to get the access token, such as `'auth.get_token'`. + The endpoint that issues access tokens, such as `'auth.get_token'`. - Customizes the property names used in the token request. + 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`). - - The property name for the client ID in the request. + + The request field name for the client ID in your API (e.g., `"clientId"`, `"client_id"`). - - The property name for the client secret in the request. + + The request field name for the client secret in your API (e.g., `"clientSecret"`, `"client_secret"`). - - The property name for the scopes in the request. + + The request field name for scopes in your API (e.g., `"scope"`, `"scopes"`). - Maps custom property names in your OAuth token response (e.g., if your API returns `accessToken` instead of `access_token`). + 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 property name for the access token in the response. + + The response field name for the access token in your API (e.g., `"accessToken"`, `"access_token"`). - - The property name for the expires in property in the response. + + The response field name for token expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). When present, the SDK automatically refreshes tokens before expiration. - The property name for the refresh token in the response. + The response field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`). Required if using the `refresh-token` flow. \ No newline at end of file diff --git a/fern/products/sdks/snippets/oauth-params.mdx b/fern/products/sdks/snippets/oauth-params.mdx index f101392df..c19c2541b 100644 --- a/fern/products/sdks/snippets/oauth-params.mdx +++ b/fern/products/sdks/snippets/oauth-params.mdx @@ -1,6 +1,10 @@ -Configure OAuth 2.0 client credentials authentication. + + 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). + -```yaml +Configure OAuth 2.0 client credentials authentication. Optionally configure a `refresh-token` endpoint for token renewal without re-authentication. + +```yaml title="generators.yml" maxLines=10 auth-schemes: my-oauth: # User-defined scheme name scheme: oauth @@ -31,15 +35,14 @@ auth-schemes: 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. + + The OAuth 2.0 grant type. Currently only `"client-credentials"` is supported. - - List of OAuth scopes to request during authentication. + + OAuth scopes to request when obtaining access tokens (e.g., `"read:users"`, `"write:orders"`). 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: Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization. - Sets the token header value prefix. + Prefix added to the access token in the Authorization header (e.g., `"Bearer"` results in `"Authorization: Bearer "`). Useful when your API expects a custom format. - Sets the token header key name. + 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"`). \ No newline at end of file diff --git a/fern/products/sdks/snippets/oauth-refresh-token.mdx b/fern/products/sdks/snippets/oauth-refresh-token.mdx index cf992a5ef..75b28c272 100644 --- a/fern/products/sdks/snippets/oauth-refresh-token.mdx +++ b/fern/products/sdks/snippets/oauth-refresh-token.mdx @@ -1,6 +1,6 @@ -Configuration for the token refresh endpoint. +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. -```yaml +```yaml title="generators.yml" refresh-token: endpoint: "auth.refresh_token" request-properties: @@ -11,23 +11,23 @@ refresh-token: ``` - The endpoint to refresh the access token, such as `'auth.refresh_token'`. + The endpoint that refreshes access tokens (e.g., `"POST /oauth/refresh"` or `"auth.refreshToken"`). - Maps custom property names in your refresh token request. + Maps OAuth parameter names to your API's request field names for the refresh flow. - - The property name for the refresh token in the request. + + The request field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`). - Maps custom property names in your refresh token response. + Maps your API's refresh response field names to OAuth standard names. - - The property name for the access token in the response. + + The response field name for the new access token (e.g., `"accessToken"`, `"access_token"`). - - The property name for the expires in property in the response. + + The response field name for the new token's expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). - - The property name for the refresh token in the response. + + The response field name if your API issues a new refresh token with each refresh (token rotation). \ No newline at end of file