feat(auth): add OAuth 2.1 client admin endpoints #1240

grdsdev · 2025-10-02T14:55:04Z

Summary

Adds OAuth 2.1 client administration endpoints to supabase-auth based on the implementation from supabase-js.

This PR implements a new admin.oauth namespace with full CRUD operations for managing OAuth clients when the OAuth 2.1 server is enabled in Supabase Auth.

Changes

New Types (`types.py`)

OAuthClient - OAuth client object returned from the OAuth 2.1 server
OAuthClientResponse - Response type for OAuth client operations
OAuthClientListResponse - Response type for listing OAuth clients with pagination
CreateOAuthClientParams - Parameters for creating a new OAuth client
PageParams and Pagination - Pagination support
Type literals for grant types, response types, client types, and registration types

New API Classes

AsyncGoTrueAdminOAuthAPI - Async OAuth admin API
SyncGoTrueAdminOAuthAPI - Sync OAuth admin API

New Admin Methods (`admin.oauth`)

list_clients(params?: PageParams) - List OAuth clients with optional pagination
create_client(params: CreateOAuthClientParams) - Register new OAuth client
update_client(client_id: str, params: UpdateOAuthClientParams) - Update an existing OAuth client
get_client(client_id: str) - Get client details by ID
delete_client(client_id: str) - Remove OAuth client
regenerate_client_secret(client_id: str) - Regenerate client secret

Tests

Comprehensive test coverage for all OAuth client operations
Tests gracefully handle cases where OAuth 2.1 server is not enabled

Implementation Notes

Follows existing patterns in the codebase (similar to admin.mfa)
Includes proper error handling and type safety
All methods require service_role key and should only be called server-side
Only relevant when the OAuth 2.1 server is enabled in Supabase Auth

References

Source PR: feat(auth): add OAuth 2.1 client admin endpoints supabase-js#1582
Related Auth PR: feat(openapi): add OAuth 2.1 server endpoints and clarify OAuth modes auth#2165

Test plan

Code passes all existing tests
New tests added for OAuth client operations
Ruff checks pass
Manual testing with OAuth 2.1 enabled server (if available)

🤖 Generated with Claude Code

- Update GoTrue from v2.175.0 to v2.180.0 - Enable OAuth server with dynamic registration in test infrastructure - Fix parsing of optional `aud` field in OAuthClientListResponse - Handle empty response bodies (204 No Content) for delete operations - Update delete test to expect null client on successful deletion All OAuth admin endpoint tests now passing, matching behavior from supabase/supabase-py#1240 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

* feat(gotrue): add OAuth 2.1 client admin endpoints Add support for OAuth 2.1 client administration endpoints in the gotrue package. This feature allows server-side management of OAuth clients through the admin API. New functionality: - admin.oauth.listClients(): List OAuth clients with pagination - admin.oauth.createClient(): Register new OAuth client - admin.oauth.getClient(): Get client details by ID - admin.oauth.deleteClient(): Remove OAuth client - admin.oauth.regenerateClientSecret(): Regenerate client secret Only relevant when OAuth 2.1 server is enabled in Supabase Auth. All methods require service_role key and should only be called server-side. Ported from: supabase/supabase-js#1582 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * test(gotrue): enable OAuth 2.1 server and fix response parsing - Update GoTrue from v2.175.0 to v2.180.0 - Enable OAuth server with dynamic registration in test infrastructure - Fix parsing of optional `aud` field in OAuthClientListResponse - Handle empty response bodies (204 No Content) for delete operations - Update delete test to expect null client on successful deletion All OAuth admin endpoint tests now passing, matching behavior from supabase/supabase-py#1240 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

silentworks · 2025-10-08T00:44:53Z

I will review this properly later today and leave any feedback here.

grdsdev · 2025-10-29T12:48:22Z

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

+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        validate_uuid(client_id)


@o-santi I'm using this uuid validation because it was already what was being used by other methods.

Since this is a new feature, does it make sense for the client_id param to be of type uuid.UUID instead of a raw str? So we don't need to validate it? We do this in Swift, but I don't know about Python.

It should be, I agree with you. But I think for now, we should maintain this behavior for consistency with the other methods, as otherwise the user might need to have some ids in str and others in UUID, which is not really intuitive.

o-santi · 2025-10-30T14:49:53Z

@grdsdev can you please merge the auth changes into this branch? I'll promptly review it after that.

Add OAuth 2.1 client administration endpoints to supabase-auth based on the implementation from supabase-js PR #1582. This adds a new `admin.oauth` namespace with full CRUD operations for managing OAuth clients when the OAuth 2.1 server is enabled. New admin.oauth methods: - list_clients() - List OAuth clients with pagination - create_client() - Register new OAuth client - get_client() - Get client details by ID - delete_client() - Remove OAuth client - regenerate_client_secret() - Regenerate client secret All methods include proper error handling and follow existing patterns (similar to admin.mfa). These methods are only relevant when the OAuth 2.1 server is enabled in Supabase Auth. References: supabase/supabase-js#1582 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> # Conflicts: # src/auth/src/supabase_auth/_async/gotrue_admin_api.py # src/auth/src/supabase_auth/_sync/gotrue_admin_api.py

Fix multiple issues with OAuth 2.1 client admin endpoints: - Add missing return statement in _request method when no xform - Handle empty responses (204 No Content) from DELETE operations - Fix list_clients to handle both list and dict response formats - Handle empty data in delete_client response - Update test expectations for DELETE operations 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

- Upgrade all GoTrue containers from v2.178.0/v2.169.0 to v2.180.0 - Enable OAuth 2.1 server on autoconfirm container for testing - Add GOTRUE_OAUTH_SERVER_ENABLED and GOTRUE_OAUTH_SERVER_ALLOW_DYNAMIC_REGISTRATION 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

o-santi · 2025-10-30T19:00:18Z

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

+        This function should only be called on a server.
+        Never expose your `service_role` key in the browser.
+        """
+        validate_uuid(client_id)


It should be, I agree with you. But I think for now, we should maintain this behavior for consistency with the other methods, as otherwise the user might need to have some ids in str and others in UUID, which is not really intuitive.

o-santi · 2025-10-30T19:01:46Z

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

+
+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: Optional[PageParams] = 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 update_client(
+        self,
+        client_id: str,
+        params: UpdateOAuthClientParams,
+    ) -> OAuthClientResponse:
+        """
+        Updates 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 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


I understand this is done to be the same as the other "namespace classes" that already exist in this package, but I believe all of these should hold the actual implementation of the class, instead of having these ugly and confusing placeholders. It can be like this for now, I will refactor this in a later PR.

grdsdev requested review from o-santi and silentworks October 6, 2025 17:14

grdsdev mentioned this pull request Oct 6, 2025

feat(gotrue): add OAuth 2.1 client admin endpoints supabase/supabase-flutter#1244

Merged

7 tasks

grdsdev commented Oct 29, 2025

View reviewed changes

grdsdev and others added 8 commits October 30, 2025 12:05

fix: validate id as uuid

bb3165f

fix: use BaseModel instead of TypedDict

a42b3f1

fix: update OAuthClient type with latest changes

b9f5562

fix: add missing uuid validations

dbd801d

fix after rebase

b9cd222

grdsdev force-pushed the feat/auth-oauth-client-admin-endpoints branch from db6d4f6 to b9cd222 Compare October 30, 2025 16:50

grdsdev added 3 commits October 30, 2025 14:10

fix tests

9c98898

fix: delete oauth returns no response

1985f42

feat(auth): add update oauth client method

be343b8

o-santi approved these changes Oct 30, 2025

View reviewed changes

grdsdev merged commit 9ab912b into main Oct 30, 2025
12 checks passed

grdsdev deleted the feat/auth-oauth-client-admin-endpoints branch October 30, 2025 19:20

github-actions bot mentioned this pull request Oct 30, 2025

chore(main): release 2.23.0 #1287

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(auth): add OAuth 2.1 client admin endpoints #1240

feat(auth): add OAuth 2.1 client admin endpoints #1240

grdsdev commented Oct 2, 2025 •

edited

Loading

Uh oh!

silentworks commented Oct 8, 2025

Uh oh!

grdsdev Oct 29, 2025

Uh oh!

o-santi Oct 30, 2025

Uh oh!

o-santi commented Oct 30, 2025

Uh oh!

o-santi Oct 30, 2025

Uh oh!

o-santi Oct 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

feat(auth): add OAuth 2.1 client admin endpoints #1240

feat(auth): add OAuth 2.1 client admin endpoints #1240

Conversation

grdsdev commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New Types (types.py)

New API Classes

New Admin Methods (admin.oauth)

Tests

Implementation Notes

References

Test plan

Uh oh!

silentworks commented Oct 8, 2025

Uh oh!

grdsdev Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

o-santi Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

o-santi commented Oct 30, 2025

Uh oh!

o-santi Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

o-santi Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

grdsdev commented Oct 2, 2025 •

edited

Loading

New Types (`types.py`)

New Admin Methods (`admin.oauth`)