You may configure Auth using either a configuration file named .env, environment variables, or a combination of both. Environment variables are prefixed with GOTRUE_, and will always have precedence over values provided via file.

​
Top-Level

GOTRUE_SITE_URL=https://example.netlify.com/
​
SITE_URL
string
required

The base URL your site is located at. Currently used in combination with other settings to construct URLs used in emails. Any URI that shares a host with SITE_URL is a permitted value for redirect_to params (see /authorize etc.).

​
URI_ALLOW_LIST
string

A comma separated list of URIs (e.g. "https://foo.example.com,https://*.foo.example.com,https://bar.example.com") which are permitted as valid redirect_to destinations. Defaults to []. Supports wildcard matching through globbing. e.g. https://*.foo.example.com will allow https://a.foo.example.com and https://b.foo.example.com to be accepted. Globbing is also supported on subdomains. e.g. https://foo.example.com/* will allow https://foo.example.com/page1 and https://foo.example.com/page2 to be accepted.

For more common glob patterns, check out the following link.

​
OPERATOR_TOKEN
string

Multi-instance mode only

The shared secret with an operator (usually Netlify) for this microservice. Used to verify requests have been proxied through the operator and the payload values can be trusted.

​
DISABLE_SIGNUP
bool
default:
"false"

When signup is disabled the only way to create new users is through invites. Defaults to false, all signups enabled.

​
GOTRUE_EXTERNAL_EMAIL_ENABLED
bool

Use this to disable email signups (users can still use external oauth providers to sign up / sign in)

​
GOTRUE_EXTERNAL_PHONE_ENABLED
bool

Use this to disable phone signups (users can still use external oauth providers to sign up / sign in)

​
GOTRUE_RATE_LIMIT_HEADER
string

Header on which to rate limit the /token endpoint.

​
GOTRUE_RATE_LIMIT_EMAIL_SENT
string

Rate limit the number of emails sent per hr on the following endpoints: /signup, /invite, /magiclink, /recover, /otp, & /user.

​
GOTRUE_PASSWORD_MIN_LENGTH
int
default:
"6"

Minimum password length, defaults to 6.

​
GOTRUE_PASSWORD_REQUIRED_CHARACTERS
string

A string of character sets separated by :. A password must contain at least one character of each set to be accepted. To use the : character escape it with \.

​
GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED
bool

If refresh token rotation is enabled, auth will automatically detect malicious attempts to reuse a revoked refresh token. When a malicious attempt is detected, gotrue immediately revokes all tokens that descended from the offending token.

​
GOTRUE_SECURITY_REFRESH_TOKEN_REUSE_INTERVAL
string

This setting is only applicable if GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED is enabled. The reuse interval for a refresh token allows for exchanging the refresh token multiple times during the interval to support concurrency or offline issues. During the reuse interval, auth will not consider using a revoked token as a malicious attempt and will simply return the child refresh token.

Only the previous revoked token can be reused. Using an old refresh token way before the current valid refresh token will trigger the reuse detection.

​
API

GOTRUE_API_HOST=localhost
PORT=9999
API_EXTERNAL_URL=http://localhost:9999

API_HOST - string

Hostname to listen on.

PORT (no prefix) / API_PORT - number

Port number to listen on. Defaults to 8081.

API_ENDPOINT - string Multi-instance mode only

Controls what endpoint Netlify can access this API on.

API_EXTERNAL_URL - string required

The URL on which Gotrue might be accessed at.

REQUEST_ID_HEADER - string

If you wish to inherit a request ID from the incoming request, specify the name in this value.

​
Database

GOTRUE_DB_DRIVER=postgres
DATABASE_URL=root@localhost/auth

DB_DRIVER - string required

Chooses what dialect of database you want. Must be postgres.

DATABASE_URL (no prefix) / DB_DATABASE_URL - string required

Connection string for the database.

GOTRUE_DB_MAX_POOL_SIZE - int

Sets the maximum number of open connections to the database. Defaults to 0 which is equivalent to an “unlimited” number of connections.

DB_NAMESPACE - string

Adds a prefix to all table names.

Migrations Note

Migrations are applied automatically when you run ./auth. However, you also have the option to rerun the migrations via the following methods:

  • If built locally: ./auth migrate
  • Using Docker: docker run --rm auth gotrue migrate

​
Logging

LOG_LEVEL=debug # available without GOTRUE prefix (exception)
GOTRUE_LOG_FILE=/var/log/go/auth.log

LOG_LEVEL - string

Controls what log levels are output. Choose from panic, fatal, error, warn, info, or debug. Defaults to info.

LOG_FILE - string

If you wish logs to be written to a file, set log_file to a valid file path.

​
Observability

Auth has basic observability built in. It is able to export OpenTelemetry metrics and traces to a collector.

​
Tracing

To enable tracing configure these variables:

GOTRUE_TRACING_ENABLED - boolean

GOTRUE_TRACING_EXPORTER - string only opentelemetry supported

Make sure you also configure the OpenTelemetry Exporter configuration for your collector or service.

For example, if you use Honeycomb.io you should set these standard OpenTelemetry OTLP variables:

OTEL_SERVICE_NAME=auth
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<API-KEY>,x-honeycomb-dataset=auth"

​
Metrics

To enable metrics configure these variables:

GOTRUE_METRICS_ENABLED - boolean

GOTRUE_METRICS_EXPORTER - string only opentelemetry and prometheus supported

Make sure you also configure the OpenTelemetry Exporter configuration for your collector or service.

If you use the prometheus exporter, the server host and port can be configured using these standard OpenTelemetry variables:

OTEL_EXPORTER_PROMETHEUS_HOST - IP address, default 0.0.0.0

OTEL_EXPORTER_PROMETHEUS_PORT - port number, default 9100

The metrics are exported on the / path on the server.

If you use the opentelemetry exporter, the metrics are pushed to the collector.

For example, if you use Honeycomb.io you should set these standard OpenTelemetry OTLP variables:

OTEL_SERVICE_NAME=auth
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<API-KEY>,x-honeycomb-dataset=auth"

Note that Honeycomb.io requires a paid plan to ingest metrics.

If you need to debug an issue with traces or metrics not being pushed, you can set DEBUG=true to get more insights from the OpenTelemetry SDK.

​
Custom resource attributes

When using the OpenTelemetry tracing or metrics exporter you can define custom resource attributes using the standard OTEL_RESOURCE_ATTRIBUTES environment variable.

A default attribute auth.version is provided containing the build version.

​
Tracing HTTP routes

All HTTP calls to the Auth API are traced. Routes use the parametrized version of the route, and the values for the route parameters can be found as the http.route.params.<route-key> span attribute.

For example, the following request:

GET /admin/users/4acde936-82dc-4552-b851-831fb8ce0927/

will be traced as:

http.method = GET
http.route = /admin/users/{user_id}
http.route.params.user_id = 4acde936-82dc-4552-b851-831fb8ce0927

​
Go runtime and HTTP metrics

All of the Go runtime metrics are exposed. Some HTTP metrics are also collected by default.

​
JSON Web Tokens (JWT)

GOTRUE_JWT_SECRET=supersecretvalue
GOTRUE_JWT_EXP=3600
GOTRUE_JWT_AUD=netlify

JWT_SECRET - string required

The secret used to sign JWT tokens with.

JWT_EXP - number

How long tokens are valid for, in seconds. Defaults to 3600 (1 hour).

JWT_AUD - string

The default JWT audience. Use audiences to group users.

JWT_ADMIN_GROUP_NAME - string

The name of the admin group (if enabled). Defaults to admin.

JWT_DEFAULT_GROUP_NAME - string

The default group to assign all new users to.

​
External Authentication Providers

We support apple, azure, bitbucket, discord, facebook, figma, github, gitlab, google, keycloak, linkedin, notion, spotify, slack, twitch, twitter and workos for external authentication.

Use the names as the keys underneath external to configure each separately.

GOTRUE_EXTERNAL_GITHUB_ENABLED=true
GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=myappclientid
GOTRUE_EXTERNAL_GITHUB_SECRET=clientsecretvaluessssh
GOTRUE_EXTERNAL_GITHUB_REDIRECT_URI=http://localhost:3000/callback

No external providers are required, but you must provide the required values if you choose to enable any.

EXTERNAL_X_ENABLED - bool

Whether this external provider is enabled or not

EXTERNAL_X_CLIENT_ID - string required

The OAuth2 Client ID registered with the external provider.

EXTERNAL_X_SECRET - string required

The OAuth2 Client Secret provided by the external provider when you registered.

EXTERNAL_X_REDIRECT_URI - string required

The URI a OAuth2 provider will redirect to with the code and state values.

EXTERNAL_X_URL - string

The base URL used for constructing the URLs to request authorization and access tokens. Used by gitlab and keycloak. For gitlab it defaults to https://gitlab.com. For keycloak you need to set this to your instance, for example: https://keycloak.example.com/realms/myrealm

​
Apple OAuth

To try out external authentication with Apple locally, you will need to do the following:

  1. Remap localhost to <my_custom_dns > in your /etc/hosts config.

  2. Configure auth to serve HTTPS traffic over localhost by replacing ListenAndServe in api.go with:

       func (a *API) ListenAndServe(hostAndPort string) {
     log := logrus.WithField("component", "api")
     path, err := os.Getwd()
     if err != nil {
       log.Println(err)
     }
     server := &http.Server{
       Addr:    hostAndPort,
       Handler: a.handler,
     }
     done := make(chan struct{})
     defer close(done)
     go func() {
       waitForTermination(log, done)
       ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
       defer cancel()
       server.Shutdown(ctx)
     }()
     if err := server.ListenAndServeTLS("PATH_TO_CRT_FILE", "PATH_TO_KEY_FILE"); err != http.ErrServerClosed {
       log.WithError(err).Fatal("http server listen failed")
     }
 }

  3. Generate the crt and key file. See here for more information.

  4. Generate the GOTRUE_EXTERNAL_APPLE_SECRET by following this post!

​
E-Mail

Sending email is not required, but highly recommended for password recovery. If enabled, you must provide the required values below.

GOTRUE_SMTP_HOST=smtp.mandrillapp.com
GOTRUE_SMTP_PORT=587
GOTRUE_SMTP_USER=smtp-delivery@example.com
GOTRUE_SMTP_PASS=correcthorsebatterystaple
GOTRUE_SMTP_ADMIN_EMAIL=support@example.com
GOTRUE_MAILER_SUBJECTS_CONFIRMATION="Please confirm"

SMTP_ADMIN_EMAIL - string required

The From email address for all emails sent.

SMTP_HOST - string required

The mail server hostname to send emails through.

SMTP_PORT - number required

The port number to connect to the mail server on.

SMTP_USER - string

If the mail server requires authentication, the username to use.

SMTP_PASS - string

If the mail server requires authentication, the password to use.

SMTP_MAX_FREQUENCY - number

Controls the minimum amount of time that must pass before sending another signup confirmation or password reset email. The value is the number of seconds. Defaults to 900 (15 minutes).

SMTP_SENDER_NAME - string

Sets the name of the sender. Defaults to the SMTP_ADMIN_EMAIL if not used.

MAILER_AUTOCONFIRM - bool

If you do not require email confirmation, you may set this to true. Defaults to false.

MAILER_OTP_EXP - number

Controls the duration an email link or otp is valid for.

MAILER_URLPATHS_INVITE - string

URL path to use in the user invite email. Defaults to /verify.

MAILER_URLPATHS_CONFIRMATION - string

URL path to use in the signup confirmation email. Defaults to /verify.

MAILER_URLPATHS_RECOVERY - string

URL path to use in the password reset email. Defaults to /verify.

MAILER_URLPATHS_EMAIL_CHANGE - string

URL path to use in the email change confirmation email. Defaults to /verify.

MAILER_SUBJECTS_INVITE - string

Email subject to use for user invite. Defaults to You have been invited.

MAILER_SUBJECTS_CONFIRMATION - string

Email subject to use for signup confirmation. Defaults to Confirm Your Signup.

MAILER_SUBJECTS_RECOVERY - string

Email subject to use for password reset. Defaults to Reset Your Password.

MAILER_SUBJECTS_MAGIC_LINK - string

Email subject to use for magic link email. Defaults to Your Magic Link.

MAILER_SUBJECTS_EMAIL_CHANGE - string

Email subject to use for email change confirmation. Defaults to Confirm Email Change.

MAILER_TEMPLATES_INVITE - string

URL path to an email template to use when inviting a user. (e.g. https://www.example.com/path-to-email-template.html) SiteURL, Email, and ConfirmationURL variables are available.

Default Content (if template is unavailable):

<h2>You have been invited</h2>

<p>
  You have been invited to create a user on {{ .SiteURL }}. Follow this link to
  accept the invite:
</p>
<p><a href="{{ .ConfirmationURL }}">Accept the invite</a></p>

MAILER_TEMPLATES_CONFIRMATION - string

URL path to an email template to use when confirming a signup. (e.g. https://www.example.com/path-to-email-template.html) SiteURL, Email, and ConfirmationURL variables are available.

Default Content (if template is unavailable):

<h2>Confirm your signup</h2>

<p>Follow this link to confirm your user:</p>
<p><a href="{{ .ConfirmationURL }}">Confirm your mail</a></p>

MAILER_TEMPLATES_RECOVERY - string

URL path to an email template to use when resetting a password. (e.g. https://www.example.com/path-to-email-template.html) SiteURL, Email, and ConfirmationURL variables are available.

Default Content (if template is unavailable):

<h2>Reset Password</h2>

<p>Follow this link to reset the password for your user:</p>
<p><a href="{{ .ConfirmationURL }}">Reset Password</a></p>

MAILER_TEMPLATES_MAGIC_LINK - string

URL path to an email template to use when sending magic link. (e.g. https://www.example.com/path-to-email-template.html) SiteURL, Email, and ConfirmationURL variables are available.

Default Content (if template is unavailable):

<h2>Magic Link</h2>

<p>Follow this link to login:</p>
<p><a href="{{ .ConfirmationURL }}">Log In</a></p>

MAILER_TEMPLATES_EMAIL_CHANGE - string

URL path to an email template to use when confirming the change of an email address. (e.g. https://www.example.com/path-to-email-template.html) SiteURL, Email, NewEmail, and ConfirmationURL variables are available.

Default Content (if template is unavailable):

<h2>Confirm Change of Email</h2>

<p>
  Follow this link to confirm the update of your email from {{ .Email }} to {{
  .NewEmail }}:
</p>
<p><a href="{{ .ConfirmationURL }}">Change Email</a></p>

​
Phone Auth

SMS_AUTOCONFIRM - bool

If you do not require phone confirmation, you may set this to true. Defaults to false.

SMS_MAX_FREQUENCY - number

Controls the minimum amount of time that must pass before sending another sms otp. The value is the number of seconds. Defaults to 60 (1 minute)).

SMS_OTP_EXP - number

Controls the duration an sms otp is valid for.

SMS_OTP_LENGTH - number

Controls the number of digits of the sms otp sent.

SMS_PROVIDER - string

Available options are: twilio, messagebird, textlocal, and vonage

Then you can use your twilio credentials:

  • SMS_TWILIO_ACCOUNT_SID
  • SMS_TWILIO_AUTH_TOKEN
  • SMS_TWILIO_MESSAGE_SERVICE_SID - can be set to your twilio sender mobile number

Or Messagebird credentials, which can be obtained in the Dashboard:

  • SMS_MESSAGEBIRD_ACCESS_KEY - your Messagebird access key
  • SMS_MESSAGEBIRD_ORIGINATOR - SMS sender (your Messagebird phone number with + or company name)

​
CAPTCHA

  • If enabled, CAPTCHA will check the request body for the captcha_token field and make a verification request to the CAPTCHA provider.

SECURITY_CAPTCHA_ENABLED - string

Whether captcha middleware is enabled

SECURITY_CAPTCHA_PROVIDER - string

for now the only options supported are: hcaptcha and turnstile

  • SECURITY_CAPTCHA_SECRET - string
  • SECURITY_CAPTCHA_TIMEOUT - string

Retrieve from hcaptcha or turnstile account

​
Reauthentication

​
SECURITY_UPDATE_PASSWORD_REQUIRE_REAUTHENTICATION
bool

Enforce reauthentication on password update.

​
Anonymous Sign-Ins

​
GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED
bool

Use this to enable/disable anonymous sign-ins.