{"id":2054,"library":"gotrue","title":"GoTrue Python Client","description":"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.","status":"active","version":"2.12.4","language":"en","source_language":"en","source_url":"https://github.com/supabase/auth-py","tags":["authentication","supabase","jwt","auth","client"],"install":[{"cmd":"pip install gotrue","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for making HTTP requests to the GoTrue API.","package":"httpx","optional":false},{"reason":"Used for handling JSON Web Tokens (JWTs) for session management.","package":"pyjwt","optional":false},{"reason":"Used for data validation and settings management.","package":"pydantic","optional":false}],"imports":[{"symbol":"GoTrueClient","correct":"from gotrue import GoTrueClient"},{"note":"For handling API-specific errors.","symbol":"GoTrueAPIError","correct":"from gotrue.exceptions import GoTrueAPIError"}],"quickstart":{"code":"import os\nfrom gotrue import GoTrueClient, GoTrueAPIError\n\n# Initialize with your Supabase URL and (anon or service_role) key\nSUPABASE_URL = os.environ.get('SUPABASE_URL', 'YOUR_SUPABASE_URL')\nSUPABASE_ANON_KEY = os.environ.get('SUPABASE_ANON_KEY', 'YOUR_SUPABASE_ANON_KEY')\n\ntry:\n    client = GoTrueClient(\n        url=f\"{SUPABASE_URL}/auth/v1\",\n        headers={\n            \"apikey\": SUPABASE_ANON_KEY\n        }\n    )\n\n    # Example: Sign up a new user\n    email = \"test@example.com\"\n    password = \"verysecretpassword\"\n    \n    response = client.sign_up(email=email, password=password)\n    print(f\"Sign-up successful: {response.user.id}\")\n\n    # You can also sign in existing users\n    # response = client.sign_in(email=email, password=password)\n    # print(f\"Sign-in successful: {response.session.access_token}\")\n\nexcept GoTrueAPIError as e:\n    print(f\"GoTrue API Error: {e.message}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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}`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"Prior to v2.10.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}