Supabase Auth (Python)

Warnings

• breaking supabase.auth.sign_in() is removed. All pre-2.0 tutorials use sign_in(). The correct method is sign_in_with_password(). Calling sign_in() raises AttributeError.
  Fix: Replace supabase.auth.sign_in({'email': ..., 'password': ...}) with supabase.auth.sign_in_with_password({'email': ..., 'password': ...})
• breaking The standalone auth package was named 'gotrue' (pip install gotrue), then renamed to 'supabase-auth'. 'from gotrue import' raises ModuleNotFoundError if only supabase-auth is installed.
  Fix: Replace 'from gotrue import' with 'from supabase_auth import'. Or just use the main supabase package which bundles auth.
• breaking Admin auth methods (list_users, create_user, delete_user) require the service_role key, NOT the anon key. Using the anon key returns 403. The distinction is not obvious — both keys look identical in format.
  Fix: For admin ops: create_client(url, os.environ['SUPABASE_SERVICE_ROLE_KEY']). Never expose service_role key to the client/browser.
• breaking sign_up() returns (user, session) where session is None if email confirmation is enabled (the default). Code that immediately uses res.session.access_token will raise AttributeError: 'NoneType' object has no attribute 'access_token'.
  Fix: Check: if res.session is not None before accessing access_token. Or disable email confirmation in Supabase dashboard for dev environments.
• breaking Realtime subscriptions only work with the async client (acreate_client). The sync client silently ignores realtime calls or raises errors.
  Fix: Use acreate_client() for any code that needs realtime. sync create_client() is for REST/auth only.
• gotcha SUPABASE_KEY should be the anon key for user-facing operations. The service_role key bypasses Row Level Security entirely — accidental use in client-side code exposes all data.
  Fix: Use anon key (SUPABASE_ANON_KEY) for client operations. Use service_role key only in server-side admin contexts.
• gotcha Default row limit is 1000 rows. Queries that return more than 1000 rows are silently truncated with no error. Agents building data pipelines hit this constantly.
  Fix: Use .range(start, end) for pagination or increase the limit in Supabase project API settings.
• gotcha supabase.auth.admin is only accessible when the client was initialized with the service_role key. Calling admin methods with the anon key returns 403 with 'not authorized' — not a clear 'wrong key' error.
  Fix: Maintain two client instances: one with anon key for user operations, one with service_role key for admin operations.

Install

• pip install supabase Python (full client — includes auth)
• pip install supabase-auth Python (standalone auth client only)

Imports

• create_client

  from supabase import create_client, Client

  gotrue-py was the old package name, now supabase-auth. 'from gotrue import' raises ModuleNotFoundError unless gotrue is still separately installed. Use the main supabase client for all auth operations in most cases.
• SyncGoTrueClient

  from supabase_auth import SyncGoTrueClient

  Package was renamed from gotrue-py to supabase-auth. The class name SyncGoTrueClient is preserved but the import path changed.

Quickstart

Client initialization and auth operations using supabase v2.x.

import os
from supabase import create_client, Client

url: str = os.environ['SUPABASE_URL']
key: str = os.environ['SUPABASE_KEY']  # anon key for client-side, service_role for admin
supabase: Client = create_client(url, key)

# Sign up
res = supabase.auth.sign_up({
    'email': 'user@example.com',
    'password': 'securepassword'
})

# Sign in — NOT sign_in(), use sign_in_with_password()
res = supabase.auth.sign_in_with_password({
    'email': 'user@example.com',
    'password': 'securepassword'
})
print(res.user)
print(res.session.access_token)

# Admin operations — requires service_role key
res = supabase.auth.admin.list_users()
for user in res:
    print(user.email)