feat: oauth2 scopes for authentication

README.md

@@ -189,9 +189,10 @@ async def main():
             method='client_credentials',
             configuration=CredentialConfiguration(
                 api_issuer=FGA_API_TOKEN_ISSUER,
-                api_audience=FGA_API_AUDIENCE,
+                api_audience=FGA_API_AUDIENCE,  # optional, required for Auth0; omit for standard OAuth2
                 client_id=FGA_CLIENT_ID,
                 client_secret=FGA_CLIENT_SECRET,
+                # scopes="read write",  # optional, space-separated OAuth2 scopes
             )
         )
     )
@@ -201,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

@@ -215,12 +215,32 @@ def validate_credentials_config(self):
                 self.configuration is None
                 or none_or_empty(self.configuration.client_id)
                 or none_or_empty(self.configuration.client_secret)
-                or none_or_empty(self.configuration.api_audience)
                 or none_or_empty(self.configuration.api_issuer)
             ):
                 raise ApiValueError(
-                    "configuration `{}` requires client_id, client_secret, api_audience and api_issuer defined for client_credentials method."
+                    f"configuration `{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.strip()
+                    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

@@ -64,16 +64,27 @@ async def _obtain_token(self, client):
         post_params = {
             "client_id": configuration.client_id,
             "client_secret": configuration.client_secret,
-            "audience": configuration.api_audience,
             "grant_type": "client_credentials",
         }
 
+        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.strip() 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

@@ -64,16 +64,27 @@ def _obtain_token(self, client):
         post_params = {
             "client_id": configuration.client_id,
             "client_secret": configuration.client_secret,
-            "audience": configuration.api_audience,
             "grant_type": "client_credentials",
         }
 
+        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.strip() 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

@@ -184,9 +184,10 @@ def test_configuration_client_credentials_missing_api_issuer(self):
         with self.assertRaises(openfga_sdk.ApiValueError):
             credential.validate_credentials_config()
 
-    def test_configuration_client_credentials_missing_api_audience(self):
+    def test_configuration_client_credentials_without_api_audience(self):
         """
-        Test credential with method client_credentials and configuration is missing api audience
+        Test credential with method client_credentials and no api_audience is valid
+        (audience is optional for standard OAuth2 servers)
         """
         credential = Credentials(
             method="client_credentials",
@@ -196,14 +197,114 @@ def test_configuration_client_credentials_missing_api_audience(self):
                 api_issuer="issuer.fga.example",
             ),
         )
-        with self.assertRaises(openfga_sdk.ApiValueError):
-            credential.validate_credentials_config()
+        credential.validate_credentials_config()
+        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
         )
@@ -216,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
@@ -242,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)