GoTrue Python Client

2.12.4 · active · verified Thu Apr 09

The `gotrue` Python client is the official library for interacting with Supabase Auth (GoTrue), allowing Python applications to manage users, sessions, and authentication flows. It's a key component of the broader `supabase-py` client. Currently at version 2.12.4, the library maintains an active release cadence with frequent updates for bug fixes and new features.

Warnings

gotcha When initializing `GoTrueClient`, ensure you provide the correct base URL for your Supabase Auth endpoint (e.g., `YOUR_SUPABASE_URL/auth/v1`). The `apikey` header should typically contain your Supabase 'anon' key for client-side operations, or a 'service_role' key for administrative tasks.
Fix: Always use `f"{SUPABASE_URL}/auth/v1"` for the `url` parameter and pass the appropriate Supabase key in the `headers` dictionary as `{"apikey": YOUR_KEY}`.
gotcha The `gotrue` client does not automatically persist user sessions across application restarts. You must implement your own session storage (e.g., in a database, local storage, or a secure cookie) and load/save sessions manually using methods like `set_session` and `get_session`.
Fix: After successful authentication, store the `session` object (e.g., `response.session`). On subsequent application runs, retrieve the stored session and pass it to `client.set_session(stored_session)` to resume the user's session.
gotcha Authentication methods that involve redirects (e.g., OAuth, email magic links) often require a `redirect_to` parameter. Ensure this URL is correctly configured in your Supabase project's Authentication settings and matches the URL provided in your client calls.
Fix: Pass `redirect_to='https://your-domain.com/auth/callback'` to methods like `sign_in_with_oauth` or `sign_up`. Verify that this redirect URL is whitelisted in your Supabase Auth settings.
deprecated The `refresh_session` method and related internal session refresh logic were updated. While the core functionality remains, direct calls to `refresh_session` might behave differently or be part of a larger internal flow. Rely on the client's internal session management when possible.
Fix: Ensure you are on the latest `gotrue` version. The client is designed to automatically refresh tokens when interacting with the API if a session is set. Focus on managing the session object itself rather than manually calling refresh if not explicitly needed.

Install

pip install gotrue Install stable version

Imports

GoTrueClient
```
from gotrue import GoTrueClient
```
GoTrueAPIError
```
from gotrue.exceptions import GoTrueAPIError
```
For handling API-specific errors.

Quickstart

This example demonstrates how to initialize the `GoTrueClient` and perform a user sign-up operation. Remember to replace placeholder URLs and keys with your actual Supabase project details, typically loaded from environment variables. Error handling for `GoTrueAPIError` is crucial for robust applications.

import os
from gotrue import GoTrueClient, GoTrueAPIError

# Initialize with your Supabase URL and (anon or service_role) key
SUPABASE_URL = os.environ.get('SUPABASE_URL', 'YOUR_SUPABASE_URL')
SUPABASE_ANON_KEY = os.environ.get('SUPABASE_ANON_KEY', 'YOUR_SUPABASE_ANON_KEY')

try:
    client = GoTrueClient(
        url=f"{SUPABASE_URL}/auth/v1",
        headers={
            "apikey": SUPABASE_ANON_KEY
        }
    )

    # Example: Sign up a new user
    email = "test@example.com"
    password = "verysecretpassword"
    
    response = client.sign_up(email=email, password=password)
    print(f"Sign-up successful: {response.user.id}")

    # You can also sign in existing users
    # response = client.sign_in(email=email, password=password)
    # print(f"Sign-in successful: {response.session.access_token}")

except GoTrueAPIError as e:
    print(f"GoTrue API Error: {e.message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →