feat(cdk): Add configurable OAuth scope property name (scopes_name)

This change adds a new 'scopes_name' parameter to OAuth authenticators,
allowing connector developers to configure the property name used for
scopes in token refresh requests. Per RFC 6749, the default is 'scope'
(singular), but some APIs require 'scopes' (plural) or other custom names.

Changes:
- Add abstract get_scopes_name() method to AbstractOauth2Authenticator
- Add scopes_name parameter to Oauth2Authenticator (default: 'scope')
- Add scopes_name parameter to SingleUseRefreshTokenOauth2Authenticator
- Add scopes_name field to DeclarativeOauth2Authenticator
- Update declarative_component_schema.yaml with scopes_name property
- Update model_to_component_factory.py to pass scopes_name
- Update tests to reflect new default behavior

Resolves: airbytehq/oncall#11127
Related: airbytehq/airbyte#54137
Co-Authored-By: unknown <>

Author: devin-ai-integration[bot]

airbyte_cdk/sources/declarative/auth/oauth.py

@@ -68,6 +68,7 @@ class DeclarativeOauth2Authenticator(AbstractOauth2Authenticator, DeclarativeAut
     client_secret_name: Union[InterpolatedString, str] = "client_secret"
     expires_in_name: Union[InterpolatedString, str] = "expires_in"
     refresh_token_name: Union[InterpolatedString, str] = "refresh_token"
+    scopes_name: Union[InterpolatedString, str] = "scope"
     refresh_request_body: Optional[Mapping[str, Any]] = None
     refresh_request_headers: Optional[Mapping[str, Any]] = None
     grant_type_name: Union[InterpolatedString, str] = "grant_type"
@@ -108,6 +109,7 @@ def __post_init__(self, parameters: Mapping[str, Any]) -> None:
         self._refresh_token_name = InterpolatedString.create(
             self.refresh_token_name, parameters=parameters
         )
+        self._scopes_name = InterpolatedString.create(self.scopes_name, parameters=parameters)
         if self.refresh_token is not None:
             self._refresh_token: Optional[InterpolatedString] = InterpolatedString.create(
                 self.refresh_token, parameters=parameters
@@ -229,6 +231,9 @@ def get_refresh_token(self) -> Optional[str]:
     def get_scopes(self) -> List[str]:
         return self.scopes or []
 
+    def get_scopes_name(self) -> str:
+        return self._scopes_name.eval(self.config)  # type: ignore # eval returns a string in this context
+
     def get_access_token_name(self) -> str:
         return self.access_token_name.eval(self.config)  # type: ignore # eval returns a string in this context
 

airbyte_cdk/sources/declarative/declarative_component_schema.yaml

@@ -1429,6 +1429,14 @@ definitions:
               "crm.objects.contacts.read",
               "crm.schema.contacts.read",
             ]
+      scopes_name:
+        title: Scopes Property Name
+        description: The name of the property to use for scopes in the token refresh request body. Per RFC 6749, the default is "scope" (singular).
+        type: string
+        default: "scope"
+        examples:
+          - scope
+          - scopes
       token_expiry_date:
         title: Token Expiry Date
         description: The access token expiry date.

airbyte_cdk/sources/declarative/models/declarative_component_schema.py

@@ -2818,6 +2818,9 @@ def create_oauth_authenticator(
                 refresh_request_headers=InterpolatedMapping(
                     model.refresh_request_headers or {}, parameters=model.parameters or {}
                 ).eval(config),
+                scopes_name=InterpolatedString.create(
+                    model.scopes_name or "scope", parameters=model.parameters or {}
+                ).eval(config),
                 scopes=model.scopes,
                 token_expiry_date_format=model.token_expiry_date_format,
                 token_expiry_is_time_of_expiration=bool(model.token_expiry_date_format),
@@ -2841,6 +2844,7 @@ def create_oauth_authenticator(
             refresh_request_headers=model.refresh_request_headers,
             refresh_token_name=model.refresh_token_name or "refresh_token",
             refresh_token=model.refresh_token,
+            scopes_name=model.scopes_name or "scope",
             scopes=model.scopes,
             token_expiry_date=model.token_expiry_date,
             token_expiry_date_format=model.token_expiry_date_format,

airbyte_cdk/sources/declarative/parsers/model_to_component_factory.py

@@ -128,7 +128,7 @@ def build_refresh_request_body(self) -> Mapping[str, Any]:
         payload[self.get_refresh_token_name()] = self.get_refresh_token()
 
         if self.get_scopes():
-            payload["scopes"] = self.get_scopes()
+            payload[self.get_scopes_name()] = self.get_scopes()
 
         if self.get_refresh_request_body():
             for key, val in self.get_refresh_request_body().items():
@@ -484,6 +484,10 @@ def get_refresh_token(self) -> Optional[str]:
     def get_scopes(self) -> List[str]:
         """List of requested scopes"""
 
+    @abstractmethod
+    def get_scopes_name(self) -> str:
+        """The name of the property to use for scopes in the token request"""
+
     @abstractmethod
     def get_token_expiry_date(self) -> AirbyteDateTime:
         """Expiration date of the access token"""

airbyte_cdk/sources/streams/http/requests_native_auth/abstract_oauth.py

@@ -38,6 +38,7 @@ def __init__(
         client_id_name: str = "client_id",
         client_secret_name: str = "client_secret",
         refresh_token_name: str = "refresh_token",
+        scopes_name: str = "scope",
         scopes: List[str] | None = None,
         token_expiry_date: AirbyteDateTime | None = None,
         token_expiry_date_format: str | None = None,
@@ -59,6 +60,7 @@ def __init__(
         self._client_id = client_id
         self._refresh_token_name = refresh_token_name
         self._refresh_token = refresh_token
+        self._scopes_name = scopes_name
         self._scopes = scopes
         self._access_token_name = access_token_name
         self._expires_in_name = expires_in_name
@@ -102,6 +104,9 @@ def get_access_token_name(self) -> str:
     def get_scopes(self) -> list[str]:
         return self._scopes  # type: ignore[return-value]
 
+    def get_scopes_name(self) -> str:
+        return self._scopes_name
+
     def get_expires_in_name(self) -> str:
         return self._expires_in_name
 
@@ -154,6 +159,7 @@ def __init__(
         self,
         connector_config: Mapping[str, Any],
         token_refresh_endpoint: str,
+        scopes_name: str = "scope",
         scopes: List[str] | None = None,
         access_token_name: str = "access_token",
         expires_in_name: str = "expires_in",
@@ -221,6 +227,7 @@ def __init__(
             client_secret=self._client_secret,
             refresh_token=self.get_refresh_token(),
             refresh_token_name=self._refresh_token_name,
+            scopes_name=scopes_name,
             scopes=scopes,
             token_expiry_date=self.get_token_expiry_date(),
             access_token_name=access_token_name,

airbyte_cdk/sources/streams/http/requests_native_auth/oauth.py

@@ -58,7 +58,7 @@ def test_refresh_request_body(self):
             refresh_request_body={
                 "custom_field": "{{ config['custom_field'] }}",
                 "another_field": "{{ config['another_field'] }}",
-                "scopes": ["no_override"],
+                "scope": ["no_override"],
             },
             parameters=parameters,
             grant_type="{{ config['grant_type'] }}",
@@ -69,7 +69,7 @@ def test_refresh_request_body(self):
             "client_id": "some_client_id",
             "client_secret": "some_client_secret",
             "refresh_token": "some_refresh_token",
-            "scopes": scopes,
+            "scope": scopes,
             "custom_field": "in_outbound_request",
             "another_field": "exists_in_body",
         }

unit_tests/sources/declarative/auth/test_oauth.py

@@ -156,7 +156,7 @@ def test_refresh_request_body(self):
             refresh_request_body={
                 "custom_field": "in_outbound_request",
                 "another_field": "exists_in_body",
-                "scopes": ["no_override"],
+                "scope": ["no_override"],
             },
         )
         body = oauth.build_refresh_request_body()
@@ -165,7 +165,7 @@ def test_refresh_request_body(self):
             "client_id": "some_client_id",
             "client_secret": "some_client_secret",
             "refresh_token": "some_refresh_token",
-            "scopes": scopes,
+            "scope": scopes,
             "custom_field": "in_outbound_request",
             "another_field": "exists_in_body",
         }
@@ -216,14 +216,15 @@ def test_refresh_request_body_with_keys_override(self):
             client_secret="some_client_secret",
             refresh_token_name="custom_refresh_token_key",
             refresh_token="some_refresh_token",
+            scopes_name="custom_scopes_key",
             scopes=["scope1", "scope2"],
             token_expiry_date=ab_datetime_now() + timedelta(days=3),
             grant_type_name="custom_grant_type",
             grant_type="some_grant_type",
             refresh_request_body={
                 "custom_field": "in_outbound_request",
                 "another_field": "exists_in_body",
-                "scopes": ["no_override"],
+                "custom_scopes_key": ["no_override"],
             },
         )
         body = oauth.build_refresh_request_body()
@@ -232,7 +233,7 @@ def test_refresh_request_body_with_keys_override(self):
             "custom_client_id_key": "some_client_id",
             "custom_client_secret_key": "some_client_secret",
             "custom_refresh_token_key": "some_refresh_token",
-            "scopes": scopes,
+            "custom_scopes_key": scopes,
             "custom_field": "in_outbound_request",
             "another_field": "exists_in_body",
         }