GoTrue is a user management and authentication server written in Go that powers Supabase‘s features such as:

• Issuing JWTs
• Row Level Security with PostgREST
• User management
• Sign in with email, password, magic link, phone number
• Sign in with external providers (Google, Apple, Facebook, Discord, …)

It is originally based on the excellent GoTrue codebase by Netlify, however both have diverged significantly in features and capabilities.

Quick Start

Create a .env file to store your own custom env vars. See example.env

1. Start the local postgres database in a postgres container: docker-compose -f docker-compose-dev.yml up postgres
2. Build the gotrue binary: make build . You should see an output like this:

go build -ldflags "-X github.com/supabase/gotrue/cmd.Version=`git rev-parse HEAD`"
GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/supabase/gotrue/cmd.Version=`git rev-parse HEAD`" -o gotrue-arm64

3. Execute the gotrue binary: ./gotrue

If you have docker installed

Create a .env.docker file to store your own custom env vars. See example.docker.env

1. make build
2. make dev
3. docker ps should show 2 docker containers (gotrue_postgresql and gotrue_gotrue)
4. That’s it! Visit the health checkendpoint to confirm that gotrue is running.

Running in production

Running an authentication server in production is not an easy feat. We recommend using Supabase Auth which gets regular security updates.

Otherwise, please make sure you setup a process to promptly update to the latest version. You can do that by following this repository, specifically the Releases and Security Advisories sections.

Backward compatibility

GoTrue uses the Semantic Versioning scheme. Here are some further clarifications on backward compatibility guarantees:

Go API compatibility

GoTrue is not meant to be used as a Go library. There are no guarantees on backward API compatibility when used this way regardless which version number changes.

Patch

Changes to the patch version guarantees backward compatibility with:

• Database objects (tables, columns, indexes, functions).
• REST API
• JWT structure
• Configuration