gotrue

GoTrue auth — user management, JWT, refresh tokens, custom claims.

SKILL.md

GitHub

GoTrue

GoTrue is a stateless authentication microservice. It issues JWTs, manages user sessions, and handles OAuth flows. Supabase embeds it as the auth service; it can also run standalone.


Detection Signals

Load this skill when any of the following are present:

Signal Location
GOTRUE_* env vars .env, .env.example, deploy config
SUPABASE_JWT_SECRET, SUPABASE_SERVICE_ROLE_KEY .env, .env.example
@supabase/supabase-js, @supabase/auth-js, @supabase/ssr package.json
supabase.auth.* calls application source
[auth] or [auth.hook.*] section supabase/config.toml
auth.users table or auth schema database schema / migrations
supabase/auth or gotrue image docker-compose.yml

Auth Methods

Method API call (supabase-js)
Email + password supabase.auth.signInWithPassword({ email, password })
Magic link supabase.auth.signInWithOtp({ email })
Phone OTP supabase.auth.signInWithOtp({ phone })
OAuth (Google, GitHub, etc.) supabase.auth.signInWithOAuth({ provider: 'google' })
Anonymous supabase.auth.signInAnonymously()
SSO / SAML supabase.auth.signInWithSSO({ domain })

Core Rules

These decide the shape of the work. Code-level detail lives in the references below.

Area Rule
Authorization source Read roles and permissions from app_metadata only — it is server-controlled
user_metadata User-writable. Never an authorization input, under any circumstance
Server-side trust getSession() does not verify — always follow with getUser() before trusting an identity on the server
Service-role key Server-side only. Reaching it from client code grants full auth admin access
Token lifetime Access tokens are short-lived (1h default); the client must handle refresh via onAuthStateChange
Claim changes Custom claims are frozen into an issued JWT — a role change only applies after a token refresh
Environment parity Confirm email-confirmation and expiry settings match between environments; GoTrue defaults differ

References

File Load when
references/client-and-admin-api.md Implementing sign-in, sessions, refresh, the Admin API, or server-side JWT verification
references/claims-and-hooks.md Adding custom claims, writing RLS against them, or configuring GoTrue hooks

Common Pitfalls

  • Reading user_metadata for authorization — users control it, never trust it for permissions
  • Not calling onAuthStateChange on the client — sessions expire silently
  • Using getSession() on the server without re-verification — the session in the cookie may be stale; always call getUser() to verify server-side
  • Exposing the service-role key in client code — gives full auth admin access
  • Not enabling email confirmations in production — GoTrue defaults may differ between environments
  • Assuming a revoked role takes effect immediately — the old JWT stays valid until it expires or is refreshed