(docs): Add OAuth SDK docs (#3615)

fern/docs.yml

@@ -115,6 +115,9 @@ navigation:
           - page: Auto-Pagination
             path: ./pages/sdks/features/auto-pagination.mdx
             icon: pro
+          - page: OAuth
+            path: ./pages/sdks/features/oauth.mdx
+            icon: pro
           - page: Retries with backoff
             path: ./pages/sdks/features/retries-with-backoff.mdx
             icon: pro

fern/pages/api-definition/fern-definition/api-yml.mdx

@@ -105,8 +105,8 @@ auth-schemes:
 ```
 </CodeBlock>
 
-Custom authentication schemes include custom `OAuth` integrations, too. Simply hook up
-your OAuth token endpoint and (optionally) configure token refresh like so:
+Custom authentication schemes include custom `OAuth` integrations, too. Simply hook up your OAuth token endpoint and
+optionally configure environment variables to read from like so:
 
 <CodeBlock title="api.yml">
 ```yaml
@@ -118,27 +118,44 @@ auth-schemes:
   OAuthScheme:
     scheme: oauth
     type: client-credentials
+    clientIdEnvVar: YOUR_CLIENT_ID
+    clientSecretEnvVar: YOUR_CLIENT_SECRET
     get-token:
-      endpoint: auth.getToken                 # Assumes the auth.yml file defines this endpoint.
-      response-properties:
-        access-token: $response.access_token
-        expires-in: $response.expires_in
-    refresh-token:
-      endpoint: auth.refreshToken             # Assumes the auth.yml file defines this endpoint.
+      endpoint: auth.getToken  # The getToken endpoint defined in the auth.yml must retrieve an access token.
+```
+</CodeBlock>
+
+If you need further customization, you can specify the `request-properties` and `response-properties` to bind specific
+properties defined on the `request` and `response`:
+
+<CodeBlock title="api.yml">
+```yaml
+name: api
+imports:
+  auth: auth.yml
+auth: OAuthScheme
+auth-schemes:
+  OAuthScheme:
+    scheme: oauth
+    type: client-credentials
+    clientIdEnvVar: YOUR_CLIENT_ID
+    clientSecretEnvVar: YOUR_CLIENT_SECRET
+    get-token:
+      endpoint: auth.getToken
       request-properties:
-        refresh-token: $request.refresh_token
+        client-id: $request.client_id
+        client-secret: $request.client_secret
       response-properties:
         access-token: $response.access_token
         expires-in: $response.expires_in
-        refresh-token: $response.refresh_token
 ```
 </CodeBlock>
 
-The `request-properties` are the properties sent to the endpoint, whereas the `response-properties` are
-used to identify and extract the OAuth access token details from the endpoint's response.
+If the `expires-in` property is set, the generated OAuth token provider will automatically refresh the token when it expires.
+Otherwise, it's assumed that the access token is valid indefinitely.
 
-With this, all of the OAuth logic happens automatically in the generated SDKs. As long as you configure your
-`client-id` and `client-secret`, your client will automatcally retrieve an access token and refresh it as needed.
+With this, all of the OAuth logic happens automatically in the generated SDKs. As long as you configure these settings, your
+client will automatcally retrieve an access token and refresh it as needed.
 
 ## Global headers
 

fern/pages/sdks/features/oauth.mdx

@@ -0,0 +1,63 @@
+---
+title: OAuth
+excerpt: Fern supports OAuth as a first class citizen
+---
+
+<Warning title='Pro Feature'>
+  This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact)
+  or [email us](mailto:[email protected]) to get started.
+</Warning>
+
+Fern supports the OAuth 2.0 authorization framework as a first class citizen. With Fern, users don't need
+to retrieve and manage access tokens manually. Instead, Fern SDKs will handle the entire OAuth flow.
+
+For the `client-credentials` OAuth flow, the user simply provides their `client-id` and `client-secret`,
+and they're ready to go.
+
+<Tabs>
+<Tab title="TypeScript">
+
+  When OAuth is configured, the TypeScript SDK's client constructor will include the `clientId` and
+  `clientSecret` parameters.
+
+  Constructing the client is as simple as:
+  ```typescript Client.ts
+  client = new Client({
+    clientId: 'YOUR_CLIENT_ID',
+    clientSecret: 'YOUR_CLIENT_SECRET',
+  });
+  ```
+
+  Behind the scenes, the `core.OAuthTokenProvider` retrieves an access token and refreshes it as needed. With this,
+  the rest of the API (like the `User` client) can use the token to authenticate every request.
+
+</Tab>
+
+<Tab title="Python">
+
+  When OAuth is configured, the Python SDK's client constructor will include the `client_id` and
+  `client_secret` parameters.
+
+  Constructing the client is as simple as:
+  ```python client.py
+  client = Client(
+    client_id="YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+  )
+  ```
+
+  Behind the scenes, the `core.OAuthTokenProvider` retrieves an access token and refreshes it as needed. With this,
+  the rest of the API (like the `UserClient`) can use the token to authenticate every request.
+
+</Tab>
+</Tabs>
+
+### Supported Authorization Flows
+
+Fern supports the following OAuth authorization flows:
+
+| Authorization Flow | Supported                                        | Example                                                      |
+|--------------------|--------------------------------------------------|--------------------------------------------------------------|
+| client-credentials | <Icon icon="check" color="#84B060" />            | [Sayari](https://github.com/sayari-analytics/sayari-python)  |
+| authorization-code | <Icon icon="check" color="#84B060" />            | [Webflow](https://github.com/webflow/webflow-python)         |
+| pkce               |                                                  |                                                              |