feat(auth): add OAuth 2.1 client admin endpoints

src/auth/infra/docker-compose.yml

@@ -2,7 +2,7 @@
 name: auth-tests
 services:
   gotrue: # Signup enabled, autoconfirm off
-    image: supabase/auth:v2.178.0
+    image: supabase/auth:v2.180.0
     ports:
       - '9999:9999'
     environment:
@@ -42,7 +42,7 @@ services:
       - db
     restart: on-failure
   autoconfirm: # Signup enabled, autoconfirm on
-    image: supabase/auth:v2.178.0
+    image: supabase/auth:v2.180.0
     ports:
       - '9998:9998'
     environment:
@@ -68,11 +68,13 @@ services:
       GOTRUE_SMTP_PASS: GOTRUE_SMTP_PASS
       GOTRUE_SMTP_ADMIN_EMAIL: admin@email.com
       GOTRUE_COOKIE_KEY: 'sb'
+      GOTRUE_OAUTH_SERVER_ENABLED: 'true'
+      GOTRUE_OAUTH_SERVER_ALLOW_DYNAMIC_REGISTRATION: 'true'
     depends_on:
       - db
     restart: on-failure
   autoconfirm_with_asymmetric_keys: # Signup enabled, autoconfirm on
-    image: supabase/auth:v2.169.0
+    image: supabase/auth:v2.180.0
     ports:
       - '9996:9996'
     environment:
@@ -102,7 +104,7 @@ services:
       - db
     restart: on-failure
   disabled: # Signup disabled
-    image: supabase/auth:v2.178.0
+    image: supabase/auth:v2.180.0
     ports:
       - '9997:9997'
     environment:

src/auth/src/supabase_auth/_async/gotrue_admin_api.py

@@ -4,7 +4,7 @@
 from typing import Dict, List, Optional
 
 from ..helpers import (
-    is_valid_uuid,
+    validate_uuid,
     model_validate,
     parse_link_response,
     parse_user_response,
@@ -16,14 +16,20 @@
     AuthMFAAdminDeleteFactorResponse,
     AuthMFAAdminListFactorsParams,
     AuthMFAAdminListFactorsResponse,
+    CreateOAuthClientParams,
     GenerateLinkParams,
     GenerateLinkResponse,
     InviteUserByEmailOptions,
+    OAuthClient,
+    OAuthClientListResponse,
+    OAuthClientResponse,
+    PageParams,
     SignOutScope,
     User,
     UserResponse,
 )
 from .gotrue_admin_mfa_api import AsyncGoTrueAdminMFAAPI
+from .gotrue_admin_oauth_api import AsyncGoTrueAdminOAuthAPI
 from .gotrue_base_api import AsyncGoTrueBaseAPI
 
 
@@ -48,6 +54,12 @@ def __init__(
         self.mfa = AsyncGoTrueAdminMFAAPI()
         self.mfa.list_factors = self._list_factors
         self.mfa.delete_factor = self._delete_factor
+        self.oauth = AsyncGoTrueAdminOAuthAPI()
+        self.oauth.list_clients = self._list_oauth_clients
+        self.oauth.create_client = self._create_oauth_client
+        self.oauth.get_client = self._get_oauth_client
+        self.oauth.delete_client = self._delete_oauth_client
+        self.oauth.regenerate_client_secret = self._regenerate_oauth_client_secret
 
     async def sign_out(self, jwt: str, scope: SignOutScope = "global") -> None:
         """
@@ -136,7 +148,7 @@ async def get_user_by_id(self, uid: str) -> UserResponse:
         This function should only be called on a server.
         Never expose your `service_role` key in the browser.
         """
-        self._validate_uuid(uid)
+        validate_uuid(uid)
 
         return await self._request(
             "GET",
@@ -155,7 +167,7 @@ async def update_user_by_id(
         This function should only be called on a server.
         Never expose your `service_role` key in the browser.
         """
-        self._validate_uuid(uid)
+        validate_uuid(uid)
         return await self._request(
             "PUT",
             f"admin/users/{uid}",
@@ -170,15 +182,15 @@ async def delete_user(self, id: str, should_soft_delete: bool = False) -> None:
         This function should only be called on a server.
         Never expose your `service_role` key in the browser.
         """
-        self._validate_uuid(id)
+        validate_uuid(id)
         body = {"should_soft_delete": should_soft_delete}
         return await self._request("DELETE", f"admin/users/{id}", body=body)
 
     async def _list_factors(
         self,
         params: AuthMFAAdminListFactorsParams,
     ) -> AuthMFAAdminListFactorsResponse:
-        self._validate_uuid(params.get("user_id"))
+        validate_uuid(params.get("user_id"))
         return await self._request(
             "GET",
             f"admin/users/{params.get('user_id')}/factors",
@@ -189,14 +201,144 @@ async def _delete_factor(
         self,
         params: AuthMFAAdminDeleteFactorParams,
     ) -> AuthMFAAdminDeleteFactorResponse:
-        self._validate_uuid(params.get("user_id"))
-        self._validate_uuid(params.get("id"))
+        validate_uuid(params.get("user_id"))
+        validate_uuid(params.get("id"))
         return await self._request(
             "DELETE",
             f"admin/users/{params.get('user_id')}/factors/{params.get('id')}",
             xform=partial(model_validate, AuthMFAAdminDeleteFactorResponse),
         )
 
-    def _validate_uuid(self, id: str) -> None:
-        if not is_valid_uuid(id):
-            raise ValueError(f"Invalid id, '{id}' is not a valid uuid")
+    async def _list_oauth_clients(
+        self,
+        params: PageParams | None = None,
+    ) -> OAuthClientListResponse:
+        """
+        Lists all OAuth clients with optional pagination.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        query = {}
+        if params:
+            if params.page is not None:
+                query["page"] = str(params.page)
+            if params.per_page is not None:
+                query["per_page"] = str(params.per_page)
+
+        response = await self._request(
+            "GET",
+            "admin/oauth/clients",
+            query=query,
+            no_resolve_json=True,
+        )
+
+        data = response.json()
+        # API may return either a list directly or a dict with "clients" key
+        clients_data = data.get("clients", data) if isinstance(data, dict) else data
+        result = OAuthClientListResponse(
+            clients=[model_validate(OAuthClient, client) for client in clients_data],
+            aud=data.get("aud") if isinstance(data, dict) else None,
+        )
+
+        # Parse pagination headers
+        total = response.headers.get("x-total-count")
+        if total:
+            result.total = int(total)
+
+        links = response.headers.get("link")
+        if links:
+            for link in links.split(","):
+                parts = link.split(";")
+                if len(parts) >= 2:
+                    page_match = parts[0].split("page=")
+                    if len(page_match) >= 2:
+                        page_num = int(page_match[1].split("&")[0].rstrip(">"))
+                        rel = parts[1].split("=")[1].strip('"')
+                        if rel == "next":
+                            result.next_page = page_num
+                        elif rel == "last":
+                            result.last_page = page_num
+
+        return result
+
+    async def _create_oauth_client(
+        self,
+        params: CreateOAuthClientParams,
+    ) -> OAuthClientResponse:
+        """
+        Creates a new OAuth client.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        return await self._request(
+            "POST",
+            "admin/oauth/clients",
+            body=params,
+            xform=lambda data: OAuthClientResponse(
+                client=model_validate(OAuthClient, data)
+            ),
+        )
+
+    async def _get_oauth_client(
+        self,
+        client_id: str,
+    ) -> OAuthClientResponse:
+        """
+        Gets details of a specific OAuth client.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        validate_uuid(client_id)
+        return await self._request(
+            "GET",
+            f"admin/oauth/clients/{client_id}",
+            xform=lambda data: OAuthClientResponse(
+                client=model_validate(OAuthClient, data)
+            ),
+        )
+
+    async def _delete_oauth_client(
+        self,
+        client_id: str,
+    ) -> OAuthClientResponse:
+        """
+        Deletes an OAuth client.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        validate_uuid(client_id)
+        return await self._request(
+            "DELETE",
+            f"admin/oauth/clients/{client_id}",
+            xform=lambda data: OAuthClientResponse(
+                client=model_validate(OAuthClient, data) if data else None
+            ),
+        )
+
+    async def _regenerate_oauth_client_secret(
+        self,
+        client_id: str,
+    ) -> OAuthClientResponse:
+        """
+        Regenerates the secret for an OAuth client.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        validate_uuid(client_id)
+        return await self._request(
+            "POST",
+            f"admin/oauth/clients/{client_id}/regenerate_secret",
+            xform=lambda data: OAuthClientResponse(
+                client=model_validate(OAuthClient, data)
+            ),
+        )

src/auth/src/supabase_auth/_async/gotrue_admin_oauth_api.py

@@ -0,0 +1,78 @@
+from ..types import (
+    CreateOAuthClientParams,
+    OAuthClientListResponse,
+    OAuthClientResponse,
+    PageParams,
+)
+
+
+class AsyncGoTrueAdminOAuthAPI:
+    """
+    Contains all OAuth client administration methods.
+    Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+    """
+
+    async def list_clients(
+        self,
+        params: PageParams | None = None,
+    ) -> OAuthClientListResponse:
+        """
+        Lists all OAuth clients with optional pagination.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        raise NotImplementedError()  # pragma: no cover
+
+    async def create_client(
+        self,
+        params: CreateOAuthClientParams,
+    ) -> OAuthClientResponse:
+        """
+        Creates a new OAuth client.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        raise NotImplementedError()  # pragma: no cover
+
+    async def get_client(
+        self,
+        client_id: str,
+    ) -> OAuthClientResponse:
+        """
+        Gets details of a specific OAuth client.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        raise NotImplementedError()  # pragma: no cover
+
+    async def delete_client(
+        self,
+        client_id: str,
+    ) -> OAuthClientResponse:
+        """
+        Deletes an OAuth client.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        raise NotImplementedError()  # pragma: no cover
+
+    async def regenerate_client_secret(
+        self,
+        client_id: str,
+    ) -> OAuthClientResponse:
+        """
+        Regenerates the secret for an OAuth client.
+        Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
+
+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        raise NotImplementedError()  # pragma: no cover

src/auth/src/supabase_auth/_async/gotrue_base_api.py

@@ -118,8 +118,16 @@ async def _request(
                 json=model_dump(body) if isinstance(body, BaseModel) else body,
             )
             response.raise_for_status()
-            result = response if no_resolve_json else response.json()
+            if no_resolve_json:
+                result = response
+            else:
+                # Handle empty responses (e.g., 204 No Content from DELETE)
+                if response.content:
+                    result = response.json()
+                else:
+                    result = {}
             if xform:
                 return xform(result)
+            return result
         except Exception as e:
             raise handle_exception(e)