PKCE uses `auth_code`; docs/standards is `code`

[dylanh724]

Bug report

• I confirm this is a bug with Supabase, not with my own application.
• I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

The Supabase Auth (GoTrue) API's PKCE token exchange endpoint uses a non-standard parameter name auth_code instead of the OAuth2 RFC 6749 standard code. This creates confusion because:

1. The OAuth2 RFC 6749 specification uses code
2. Supabase's own documentation consistently refers to code
3. All official Supabase SDKs expect and document code
4. The OpenAPI spec contradicts both the docs and the OAuth2 standard

To Reproduce

1. Check the OpenAPI specification: https://github.com/supabase/auth/blob/master/openapi.yaml#L102

   • Shows parameter named auth_code for PKCE flow

2. Compare with Supabase documentation: https://supabase.com/docs/guides/auth/sessions/pkce-flow

   • States: "The code parameter is commonly known as the Auth Code"

3. Compare with OAuth2 standard (❗that your PKCE docs link to): https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2

   • Specifies authorization response returns parameter named code
   

4. Check SDK implementations expecting code:

   • C# SDK: ExchangeCodeForSession(string codeVerifier, string authCode) - parameter named authCode but docs reference "code"
   • JavaScript SDK: exchangeCodeForSession(code) - parameter named code
   • All examples show extracting code from URL query params

Expected behavior

The API should use code to match:

1. OAuth2 RFC 6749 specification (https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2):

   • Section 4.1.2 Authorization Response specifies parameter code

2. Supabase's own documentation:

   • PKCE Flow docs: "The code parameter..." (https://supabase.com/docs/guides/auth/sessions/pkce-flow)
   • OAuth 2.1 Flows docs show: 'code=<authorization-code>' (https://supabase.com/docs/guides/auth/oauth-server/oauth-flows)
   • All provider docs: const code = requestUrl.searchParams.get("code")

3. Standard OAuth2 implementations:

   • Google, GitHub, Microsoft all use code
   • Supabase's redirect URLs contain ?code=xyz, not ?auth_code=xyz

Current vs. Expected

Current (OpenAPI spec):

auth_code:
  type: string
  description: Auth code from PKCE flow

Expected (OAuth2 standard):

code:
  type: string
  description: Authorization code from OAuth2 PKCE flow

Impact

This inconsistency:

• Violates OAuth2 standards without justification
• Contradicts Supabase's own documentation
• Creates confusion for developers implementing PKCE flows
• Forces SDK maintainers to use non-standard parameter names or do parameter mapping
• Makes Supabase Auth incompatible with standard OAuth2 tooling

Evidence Links

OpenAPI spec using auth_code:

• https://github.com/supabase/auth/blob/master/openapi.yaml#L102

Supabase docs using code:

• https://supabase.com/docs/guides/auth/sessions/pkce-flow
• https://supabase.com/docs/guides/auth/oauth-server/oauth-flows

OAuth2 RFC 6749 standard:

• https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2

SDK implementations:

• C# SDK docs: https://supabase-community.github.io/gotrue-csharp/api/Supabase.Gotrue.Client.html
• JavaScript SDK: https://supabase.com/docs/reference/javascript/auth-exchangecodeforsession

System information

• Affected: Supabase Auth (GoTrue) API
• Version: Current production
• Impact: All SDKs and direct API users

Additional context

The parameter should be renamed from auth_code to code in the actual API implementation to:

1. Comply with OAuth2 RFC 6749
2. Match Supabase's documentation
3. Align with all major OAuth2 providers
4. Eliminate confusion between docs and implementation

This appears to be a case where the implementation diverged from both standards and documentation without updating either consistently.