Repository navigation
openapi.yaml seems to drift from the admin handlers in several places #2859
Description
As part of my planning process for capability additions to our new, official Go SDK, I am getting Claude to scope by looking across existing SDK implementations as well as upstream specs and implementations where that makes sense. For my latest round of planning, it has identified some potential fixups in this repository which might be better triaged and ultimately handled by those who understand this repository at a deeper level...
🤖 Claude's Summary
Found while writing SDK capability specs against openapi.yaml at 0907af9:
PUT /admin/users/{userId}/factors/{factorId}documents an empty request body. The handler readsfriendly_nameandphone(internal/api/admin.go,adminUserUpdateFactorParams).GET /admin/auditdocumentspageandper_pageonly. The handler also reads aqueryfilter of the form<author|action|type>:<text>(internal/api/audit.go,adminAuditLog).POST /admin/sso/providersdocuments a 200 response. The handler returns 201 (internal/api/ssoadmin.go,adminSSOProvidersCreate).POSTandPUT /admin/sso/providersdocument neithername_id_format,resource_idnordisabled, and{ssoProviderId}is documented as a UUID althoughresource_<resource_id>is accepted (loadSSOProvider).GET /admin/sso/providersdocuments no query parameters. The handler readsresource_idandresource_id_prefixfilters.SSOProviderSchemanames the domain listsso_domains. The wire field isdomains(internal/models/sso.go,SSOProvider).- The SSO create and update operations do not document their 422 responses (
saml_idp_already_existson create,conflicton update). POST /admin/generate_linklists fivetypevalues. The handler also acceptsinvite.DELETE /admin/users/{userId}documents no request body. The handler readsshould_soft_delete.GET /admin/usersandGET /admin/auditdocument no response headers. Both setX-Total-CountandLinkfor pagination (internal/api/pagination.go,addPaginationHeaders).
Related:
Activity
docs(auth): link the OpenAPI drift pointers in the admin specs to `su…
QuintinWillison commentedon Oct 8, 2026
An eleventh item, found while writing the SDK capability spec for
admin.delete_user(supabase/sdk#259, where the spec's API section points at the handler for this):DELETE /admin/users/{userId}documents the deleted user (UserSchema, "User's account data") as the 200 response body. The handler answers with an empty JSON object, and has since 2017 (internal/api/admin.go,adminUserDelete,sendJSON(w, http.StatusOK, map[string]interface{}{})). supabase-js types the call's result from the documented shape and so returns an empty object typed as a user.haranishi commentedon Oct 11, 2026
I checked the eleven reported discrepancies against the current admin handlers and models. I am preparing a documentation-only patch to
openapi.yamlcovering the request fields, filters, SSO response codes and field names, pagination headers, and the empty admin-delete response. I will validate the OpenAPI structure and references and compare the documented shapes with the server source before opening a PR.haranishi commentedon Oct 11, 2026
Implemented all eleven reported specification discrepancies in Draft PR #2866. The changes were compared with the current handlers, pagination helpers, SSO models, and pinned SAML NameID-format constants.
Formatting and whitespace checks pass. OpenAPI structure/reference validation adds no issues and finds no unresolved references; the three pre-existing structural errors are documented in the PR. Generating the admin Go client with the pinned oapi-codegen v2.8.0 produces reproducible output that compiles and passes the Go vet checks. The submitted diff stays in
openapi.yaml, because committing the generated output would change existing Go method signatures and needs a separate compatibility review.The related JavaScript SDK deletion-response correction is submitted to v3 in supabase/supabase-js#2758, with local hard/soft-deletion coverage.
#2866