feat: add blank.whitespace handling + docs

Author: SoulPancake

README.md

@@ -202,6 +202,37 @@ async def main():
         return api_response
 ```
 
+> **Note:** `api_issuer` accepts either a hostname (e.g., `issuer.fga.example`, which defaults to `https://<hostname>/oauth/token`) or a full token endpoint URL (e.g., `https://oauth.fga.example/token`). Use the full URL when your OAuth2 provider uses a non-standard token endpoint path.
+
+#### OAuth2 Client Credentials (Standard OAuth2)
+
+For OAuth2 providers that use `scope` instead of `audience`:
+
+```python
+from openfga_sdk import ClientConfiguration, OpenFgaClient
+from openfga_sdk.credentials import Credentials, CredentialConfiguration
+
+
+async def main():
+    configuration = ClientConfiguration(
+        api_url=FGA_API_URL,  # required
+        store_id=FGA_STORE_ID,  # optional
+        authorization_model_id=FGA_MODEL_ID,  # optional
+        credentials=Credentials(
+            method='client_credentials',
+            configuration=CredentialConfiguration(
+                api_issuer="https://oauth.fga.example/token",  # full token endpoint URL
+                client_id=FGA_CLIENT_ID,
+                client_secret=FGA_CLIENT_SECRET,
+                scopes="email profile",  # space-separated OAuth2 scopes
+            )
+        )
+    )
+    async with OpenFgaClient(configuration) as fga_client:
+        api_response = await fga_client.read_authorization_models()
+        return api_response
+```
+
 ### Custom Headers
 
 #### Default Headers

openfga_sdk/credentials.py

@@ -221,5 +221,26 @@ def validate_credentials_config(self):
                     "configuration `{}` requires client_id, client_secret and api_issuer defined for client_credentials method."
                 )
 
+            # Normalize blank/whitespace values to None
+            # (common misconfiguration from env vars like FGA_API_AUDIENCE="")
+            if (
+                isinstance(self.configuration.api_audience, str)
+                and self.configuration.api_audience.strip() == ""
+            ):
+                self.configuration.api_audience = None
+            if (
+                isinstance(self.configuration.scopes, str)
+                and self.configuration.scopes.strip() == ""
+            ):
+                self.configuration.scopes = None
+            if isinstance(self.configuration.scopes, list):
+                self.configuration.scopes = [
+                    s
+                    for s in self.configuration.scopes
+                    if isinstance(s, str) and s.strip()
+                ]
+                if not self.configuration.scopes:
+                    self.configuration.scopes = None
+
             # validate token issuer
             self._parse_issuer(self.configuration.api_issuer)

openfga_sdk/oauth2.py

@@ -67,15 +67,24 @@ async def _obtain_token(self, client):
             "grant_type": "client_credentials",
         }
 
-        if configuration.api_audience is not None:
+        if (
+            configuration.api_audience is not None
+            and configuration.api_audience.strip()
+        ):
             post_params["audience"] = configuration.api_audience
 
         # Add scope parameter if scopes are configured
         if configuration.scopes is not None:
             if isinstance(configuration.scopes, list):
-                post_params["scope"] = " ".join(configuration.scopes)
+                scope_str = " ".join(s for s in configuration.scopes if s and s.strip())
             else:
-                post_params["scope"] = configuration.scopes
+                scope_str = (
+                    configuration.scopes.strip()
+                    if isinstance(configuration.scopes, str)
+                    else ""
+                )
+            if scope_str:
+                post_params["scope"] = scope_str
 
         headers = urllib3.response.HTTPHeaderDict(
             {

openfga_sdk/sync/oauth2.py

@@ -67,15 +67,24 @@ def _obtain_token(self, client):
             "grant_type": "client_credentials",
         }
 
-        if configuration.api_audience is not None:
+        if (
+            configuration.api_audience is not None
+            and configuration.api_audience.strip()
+        ):
             post_params["audience"] = configuration.api_audience
 
         # Add scope parameter if scopes are configured
         if configuration.scopes is not None:
             if isinstance(configuration.scopes, list):
-                post_params["scope"] = " ".join(configuration.scopes)
+                scope_str = " ".join(s for s in configuration.scopes if s and s.strip())
             else:
-                post_params["scope"] = configuration.scopes
+                scope_str = (
+                    configuration.scopes.strip()
+                    if isinstance(configuration.scopes, str)
+                    else ""
+                )
+            if scope_str:
+                post_params["scope"] = scope_str
 
         headers = urllib3.response.HTTPHeaderDict(
             {

test/credentials_test.py

@@ -201,11 +201,110 @@ def test_configuration_client_credentials_without_api_audience(self):
         self.assertEqual(credential.method, "client_credentials")
         self.assertIsNone(credential.configuration.api_audience)
 
+    def test_configuration_client_credentials_blank_api_audience_normalized(self):
+        """
+        Test that blank/whitespace api_audience is normalized to None
+        (common misconfiguration from env vars like FGA_API_AUDIENCE="")
+        """
+        credential = Credentials(
+            method="client_credentials",
+            configuration=CredentialConfiguration(
+                client_id="myclientid",
+                client_secret="mysecret",
+                api_issuer="issuer.fga.example",
+                api_audience="",
+            ),
+        )
+        credential.validate_credentials_config()
+        self.assertIsNone(credential.configuration.api_audience)
+
+    def test_configuration_client_credentials_whitespace_api_audience_normalized(self):
+        """
+        Test that whitespace-only api_audience is normalized to None
+        """
+        credential = Credentials(
+            method="client_credentials",
+            configuration=CredentialConfiguration(
+                client_id="myclientid",
+                client_secret="mysecret",
+                api_issuer="issuer.fga.example",
+                api_audience="   ",
+            ),
+        )
+        credential.validate_credentials_config()
+        self.assertIsNone(credential.configuration.api_audience)
+
+    def test_configuration_client_credentials_blank_scopes_normalized(self):
+        """
+        Test that blank scopes string is normalized to None
+        """
+        credential = Credentials(
+            method="client_credentials",
+            configuration=CredentialConfiguration(
+                client_id="myclientid",
+                client_secret="mysecret",
+                api_issuer="issuer.fga.example",
+                scopes="",
+            ),
+        )
+        credential.validate_credentials_config()
+        self.assertIsNone(credential.configuration.scopes)
+
+    def test_configuration_client_credentials_whitespace_scopes_normalized(self):
+        """
+        Test that whitespace-only scopes string is normalized to None
+        """
+        credential = Credentials(
+            method="client_credentials",
+            configuration=CredentialConfiguration(
+                client_id="myclientid",
+                client_secret="mysecret",
+                api_issuer="issuer.fga.example",
+                scopes="   ",
+            ),
+        )
+        credential.validate_credentials_config()
+        self.assertIsNone(credential.configuration.scopes)
+
+    def test_configuration_client_credentials_empty_scopes_list_normalized(self):
+        """
+        Test that empty scopes list is normalized to None
+        """
+        credential = Credentials(
+            method="client_credentials",
+            configuration=CredentialConfiguration(
+                client_id="myclientid",
+                client_secret="mysecret",
+                api_issuer="issuer.fga.example",
+                scopes=[],
+            ),
+        )
+        credential.validate_credentials_config()
+        self.assertIsNone(credential.configuration.scopes)
+
+    def test_configuration_client_credentials_blank_scopes_list_normalized(self):
+        """
+        Test that scopes list with only blank strings is normalized to None
+        """
+        credential = Credentials(
+            method="client_credentials",
+            configuration=CredentialConfiguration(
+                client_id="myclientid",
+                client_secret="mysecret",
+                api_issuer="issuer.fga.example",
+                scopes=["", "  "],
+            ),
+        )
+        credential.validate_credentials_config()
+        self.assertIsNone(credential.configuration.scopes)
+
 
 class TestCredentialsIssuer(IsolatedAsyncioTestCase):
     def setUp(self):
         # Setup a basic configuration that can be modified per test case
-        self.configuration = CredentialConfiguration(api_issuer="https://example.com")
+        self.configuration = CredentialConfiguration(
+            api_issuer="https://abc.fga.example"
+        )
         self.credentials = Credentials(
             method="client_credentials", configuration=self.configuration
         )
@@ -218,15 +317,15 @@ def test_valid_issuer_https(self):
 
     def test_valid_issuer_with_oauth_endpoint_https(self):
         # Test a valid HTTPS URL
-        self.configuration.api_issuer = "https://example.com/oauth/token"
+        self.configuration.api_issuer = "https://abc.fga.example/oauth/token"
         result = self.credentials._parse_issuer(self.configuration.api_issuer)
-        self.assertEqual(result, "https://example.com/oauth/token")
+        self.assertEqual(result, "https://abc.fga.example/oauth/token")
 
     def test_valid_issuer_with_some_endpoint_https(self):
         # Test a valid HTTPS URL
-        self.configuration.api_issuer = "https://example.com/oauth/some/endpoint"
+        self.configuration.api_issuer = "https://abc.fga.example/oauth/some/endpoint"
         result = self.credentials._parse_issuer(self.configuration.api_issuer)
-        self.assertEqual(result, "https://example.com/oauth/some/endpoint")
+        self.assertEqual(result, "https://abc.fga.example/oauth/some/endpoint")
 
     def test_valid_issuer_http(self):
         # Test a valid HTTP URL
@@ -244,7 +343,7 @@ def test_invalid_issuer_no_scheme(self):
 
     def test_invalid_issuer_bad_scheme(self):
         # Test an issuer with an unsupported scheme
-        self.configuration.api_issuer = "ftp://example.com"
+        self.configuration.api_issuer = "ftp://abc.fga.example"
         with self.assertRaises(ApiValueError):
             self.credentials._parse_issuer(self.configuration.api_issuer)