Open-source project
netlify/gotrue avatar
netlify/gotrue

netlify/gotrue: a self-hosted JWT user management API for Jamstack projects

An JWT based API for managing users and issuing JWT tokens.

4,505 stars326 forksGoMIT

At a glance

What is it?
GoTrue is a small Go service that handles signup, login and token issuing for APIs, with MySQL as its only supported database and migrations you run yourself. The Docker image and the migrate command are the fastest way to judge it.
Who is it for?
Adopt GoTrue if you want a small Go service that owns signup, login and JWT issuing, you are willing to run MySQL, and you accept running migrations as a separate step. Do not adopt it if you need Postgres, a managed control plane, or a UI out of the box; the README describes an API, not a product.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 19 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • netlify/gotrue4,505 ★ · +18
Star history
Repository2026-09-232026-11-14
netlify/gotrue4.5k4.5k

18 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What problem GoTrue solves, and for whom

The README describes GoTrue as "a small open-source API written in Golang, that can act as a self-standing API service for handling user registration and authentication for Jamstack projects." That sentence sets the scope tightly. It is a user store plus a token issuer, not an identity platform with a dashboard. If your static frontend needs to create accounts, verify email addresses, issue signed tokens and let people reset passwords, GoTrue is the backend for that, and it is designed to sit behind whatever serves your site.

The intended operator is someone comfortable running a Go binary next to a database. Configuration is read from a `.env` file, environment variables, or both, with environment variables taking precedence. Every setting is prefixed `GOTRUE_` except a handful of exceptions such as `PORT`, `DATABASE_URL` and `LOG_LEVEL`. That design shows the deployment target: a container or a process manager where the entire configuration arrives as environment variables.

Nothing in the documentation positions GoTrue as a general-purpose identity provider for a large enterprise directory. It handles users, groups, external OAuth providers and email, and it stops there.

How GoTrue issues tokens and stores users

The mechanism is straightforward. A client posts credentials to the API, GoTrue checks them against its user table, and it returns a JWT signed with `JWT_SECRET`. The default lifetime is `JWT_EXP=3600`, one hour, and the audience defaults to whatever `JWT_AUD` is set to. Groups are part of the token model: `JWT_ADMIN_GROUP_NAME` defaults to `admin` and `JWT_DEFAULT_GROUP_NAME` assigns new users to a group on creation. That is how the project expresses roles without a separate permissions service.

Persistence is MySQL only. The README states that `DB_DRIVER` "Must be `mysql`", and the `go.mod` file lists `github.com/go-sql-driver/mysql` plus `github.com/gobuffalo/pop/v5` for the ORM and migration layer. `DB_NAMESPACE` adds a prefix to every table name, which is how you would run GoTrue alongside other applications in one schema.

Rate limiting is handled by `GOTRUE_RATE_LIMIT_HEADER`, which names the header the `/token` endpoint is limited on, and the dependency list includes `github.com/didip/tollbooth/v5`, a Go rate-limiting library. Tracing is optional and, per the README, only the Datadog tracer is supported, configured through `GOTRUE_TRACING_ENABLED`, `GOTRUE_TRACING_HOST`, `GOTRUE_TRACING_PORT`, `GOTRUE_TRACING_TAGS` and `GOTRUE_SERVICE_NAME`. The `dd-trace-go` dependency in `go.mod` is consistent with that statement.

External identity is delegated. The README says `bitbucket`, `github`, `gitlab` and `google` are supported, each configured under an `external` key with `EXTERNAL_X_ENABLED`, `EXTERNAL_X_CLIENT_ID` and `EXTERNAL_X_SECRET`. GitLab additionally requires `EXTERNAL_X_REDIRECT_URI` and uses `EXTERNAL_X_URL`, which defaults to `https://gitlab.com`. No provider is mandatory.

Installing GoTrue and running the first migration

The repository ships a Dockerfile that builds the binary with Go 1.25 and copies the `migrations` directory into the runtime image. That copy matters, because migrations are not applied automatically. The README is explicit: "Migrations are not applied automatically, so you will need to run them after you've built gotrue."

The image sets `GOTRUE_DB_MIGRATIONS_PATH=/usr/local/etc/gotrue/migrations`, so a container started from it already knows where the migration files live. To build the image from a checkout:

bash
docker build -t gotrue .

The README gives the migration invocation for the Docker path directly. Run it once against a reachable database before starting the server:

bash
docker run --rm gotrue gotrue migrate

The same document gives the local equivalent for a binary you built yourself:

bash
./gotrue migrate

The Makefile exposes `make build` for the binary and `make image` for the Docker image, plus `migrate_dev` and `migrate_test`, which call `hack/migrate.sh` with the `development` and `test` arguments. If you build locally rather than in Docker, run `make deps` first; it installs the `soda` migration tool and `golangci-lint` before downloading modules.

Configuration is the part people get wrong. `SITE_URL`, `JWT_SECRET`, `DB_DRIVER` and `DATABASE_URL` are all marked required in the README, and `DB_DRIVER` must be `mysql`. A minimal environment for a local run looks like this, using only keys the README documents:

properties
GOTRUE_SITE_URL=http://localhost:8081/
GOTRUE_DB_DRIVER=mysql
DATABASE_URL=root@localhost/gotrue
GOTRUE_JWT_SECRET=supersecretvalue

The README notes that `PORT` and `DATABASE_URL` are used without the `GOTRUE_` prefix, and that the default port is 8081. The README documents the `/token` endpoint as the one subject to header-based rate limiting. Email is optional but recommended for password recovery, and `MAILER_AUTOCONFIRM` controls whether confirmation is skipped entirely.

Where GoTrue is the wrong tool

The MySQL requirement is the first hard boundary. If your stack is Postgres, GoTrue as documented here does not offer a driver for you; `DB_DRIVER` must be `mysql`, and the migration files under `migrations/` are written for that dialect. Anyone who wants the Supabase-hosted variant of this code is looking at a different deployment story, because the README describes a self-standing service with a connection string, not a managed offering.

The second boundary is operational. Migrations are a manual step: the README gives `./gotrue migrate` and the Docker equivalent, and the Makefile adds `migrate_dev` and `migrate_test`. Treat a migration against production as something you rehearse on a copy first.

The third is scope. User export is documented through `GOTRUE_API_EXPORT_SECRET`, described as a secret that, when set, allows exporting users for migration to a different service. That is a migration escape hatch, not a reporting feature. If your requirement is a console where support staff can search accounts and disable them, this is not that product.

Multi-instance deployments add another constraint. `OPERATOR_TOKEN` and `GOTRUE_API_ENDPOINT` are both marked "Multi-instance mode only" and are described in terms of a Netlify operator proxying requests and trusting payload values. If you are not running behind that operator, those settings are not for you.

GoTrue compared with a full identity platform such as Keycloak

The comparison people search for is GoTrue against Keycloak, and the difference is architectural rather than cosmetic. Keycloak is a Java application that ships its own administration console, realm model and protocol surface across OIDC and SAML. GoTrue is a single Go binary that speaks OAuth2 and JWT, stores users in MySQL, and leaves the interface to whatever you build on top of its HTTP endpoints. The `go.mod` file does list `github.com/russellhaering/gosaml2` and `goxmldsig`, so SAML support exists in the dependency tree, but the README's external authentication section names only Bitbucket, GitHub, GitLab and Google. Do not plan a SAML rollout on the dependency list alone.

The practical consequence is administrative. With Keycloak you get a console and a realm abstraction; with GoTrue you get endpoints and a users table you query yourself. That is cheaper to run and easier to embed in a Jamstack deployment, and it is more work the moment a non-engineer needs to manage accounts.

The same logic separates GoTrue from building authentication directly into your application. Writing your own signup, confirmation email, password reset and token signing is not hard in isolation, but the pieces GoTrue already handles are the ones that go wrong quietly: `SMTP_MAX_FREQUENCY` throttles confirmation and reset emails to a 900-second default, `SMTP_RESERVED_DOMAINS` blocks sender domains you own from being spoofed in the `admin_email` field, and `DISABLE_SIGNUP` lets you close registration so that only invites create users. Those defaults are the argument for using the project rather than a hand-rolled equivalent.

Maintenance status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-10-27. The release tags tell a different story: v1.0.0 was published on 2020-12-14 and v1.0.1 on 2022-02-09. Commits continue while tagged releases have not, so if your deployment process depends on release artifacts rather than a commit or a locally built image, you are consuming unreleased code. That is a real consideration for anyone pinning versions. The Dockerfile builds from source in the repository, and `make build` stamps the binary with the current commit hash through `-X github.com/netlify/gotrue/cmd.Version`, which is the version signal the project itself provides.

The licence is MIT, which is permissive and places few conditions on redistribution or modification. That is a statement about the licence text, not advice about your situation; if you are embedding GoTrue in a commercial product, have your own counsel read the LICENSE file rather than relying on a summary.

Upgrade cost concentrates in two places. The migration directory is the first: because migrations do not run automatically, every upgrade that touches the schema needs a rehearsal against a copy of your data. The second is configuration drift. The README documents a large environment surface, and a new release can add keys such as `SMTP_RESERVED_DOMAINS` without changing how existing ones behave. Diffing your `.env` against `example.env` in the repository root is the cheapest way to catch that, since the repository ships that file alongside the README.

Editorial conclusion

Adopt GoTrue if you want a small Go service that owns signup, login and JWT issuing, you are willing to run MySQL, and you accept running migrations as a separate step. Do not adopt it if you need Postgres, a managed control plane, or a UI out of the box; the README describes an API, not a product. Verify the migration path first: build the binary or pull the image, run the migrate command against a disposable database, and confirm the tables match the DB_NAMESPACE you intend to use.

Frequently asked questions

What is GoTrue?

GoTrue is a small open-source API written in Go that handles user registration and authentication for Jamstack projects, based on OAuth2 and JWT. It manages signup, authentication and custom user data, and stores users in MySQL.

What is GoTrue in Supabase?

GoTrue is described in the README as a self-standing API service with its own configuration, database connection string and migration step.

What is the difference between GoTrue and Supabase Auth?

GoTrue as documented here is a Go binary you run yourself against a MySQL database, configured through GOTRUE_ environment variables, with migrations applied by hand.

What are the alternatives to GoTrue?

The architectural contrast is with full identity platforms such as Keycloak, which ship an administration console and a realm model, while GoTrue exposes HTTP endpoints and leaves the interface to you.

Official sources

  1. License: MIT
  2. netlify/gotrue on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/netlify-gotrue.svg)](https://hysenlabs.com/projects/netlify-gotrue)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/netlify-gotrue.svg)](https://hysenlabs.com/projects/netlify-gotrue)

Was this useful?