Auth Server

GoTrue is an open source Auth server written in Go. It is an API server that handles user registration, authentication, and managing user data inside a PostgreSQL database.

The Supabase Platform exposes a subset of these configuration options in the dashboard. If you're self-hosting GoTrue, these configuration options are maintained as environment variables.

Security

Parameter	Type	Description
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") 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	The shared secret with an operator for this microservice. Used to verify requests have been proxied through the operator and the payload values can be trusted.
DISABLE_SIGNUP	bool	When signup is disabled the only way to create new users is through invites. Defaults to false, all signups enabled.
EXTERNAL_EMAIL_ENABLED	bool	Use this to disable email signups (users can still use external oauth providers to sign up / sign in)
EXTERNAL_PHONE_ENABLED	bool	Use this to disable phone signups (users can still use external oauth providers to sign up / sign in)
RATE_LIMIT_TOKEN_REFRESH	string	Rate limit the number of requests sent to /token
RATE_LIMIT_EMAIL_SENT	string	Rate limit the number of emails sent per hr on the following endpoints: /signup, /invite, /magiclink, /recover, /otp, & /user.
PASSWORD_MIN_LENGTH	int	Minimum password length, defaults to 6.

These options control additional security settings available in gotrue. If self-hosting, they need to be prefixed with GOTRUE_SECURITY_ .

Parameter	Type	Description
REFRESH_TOKEN_ROTATION_ENABLED	bool	If refresh token rotation is enabled, gotrue 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.
REFRESH_TOKEN_REUSE_INTERVAL	string	This setting is only applicable if 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, gotrue 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.
CAPTCHA_ENABLED	string	Enables the captcha middleware.
CAPTCHA_PROVIDER	string	The only captcha provider option supported is: hcaptcha.
CAPTCHA_SECRET	string	The captcha secret token. Retrieve this from your captcha account.
CAPTCHA_TIMEOUT	string	The http timeout on the captcha request.
UPDATE_PASSWORD_REQUIRE_REAUTHENTICATION	bool	When enabled, this requires a user to reauthenticate before being able to update their password.

API

Parameter	Type	Description
API_HOST	string	Hostname to listen on.
PORT	number	Port number to listen on. Defaults to 8081.
REQUEST_ID_HEADER	string	If you wish to inherit a request ID from the incoming request, specify the name in this value.

Database

Parameter	Type	Description
DB_DRIVER	string	Required. Chooses what dialect of database you want. Must be postgres.
DATABASE_URL	string	Required. Connection string for the database.
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	Specifies the schema in which the tables are to be created in.

JSON Web Tokens (JWT)

Parameter	Type	Description
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. Defaults to authenticated.
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, 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.

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

Parameter	Type	Description
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. Also known as the callback url, this is the URI an 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 realm url, (e.g. https://keycloak.example.com/auth/realms/myrealm)

Apple OAuth

To try out sign-in with Apple locally, you will need to do the following:

1. Run GoTrue over https via a reverse proxy (like ngrok).
2. Generate the crt and key file. See here for more information.
3. Generate the GOTRUE_EXTERNAL_APPLE_SECRET by following this post!

SMTP Configuration

Sending email is not required, but highly recommended for password recovery. If mailer_autoconfirm is enabled, no emails will be sent out for signup, recovery, invite. Emails will only be sent out for magiclink.

Parameter	Type	Description
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	string	Required. The port number to connect to the mail server on.
SMTP_USER	string	Required. If the mail server requires authentication, the username to use.
SMTP_PASS	string	Required. If the mail server requires authentication, the password to use.
SMTP_MAX_FREQUENCY	string	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 60 seconds.
SMTP_SENDER_NAME	string	Sets the name of the sender. Defaults to the SMTP_ADMIN_EMAIL if not used.

Email

These options control the emails sent from GoTrue.

Parameter	Type	Description
MAILER_AUTOCONFIRM	bool	If you do not require email confirmation, you may set this to true. Defaults to false.
MAILER_SECURE_EMAIL_CHANGE_ENABLED	bool	If true, send an email to both the user's current and new email with a confirmation link, otherwise send an email with confirmation link only to new email. Defaults to true.
MAILER_OTP_EXP	string	Controls the duration an email link or otp is valid for. Defaults to 24 hrs.
MAILER_URLPATHS_INVITE	string	URL path to use in the user invite email. Defaults to /.
MAILER_URLPATHS_CONFIRMATION	string	URL path to use in the signup confirmation email. Defaults to /.
MAILER_URLPATHS_RECOVERY	string	URL path to use in the password reset email. Defaults to /.
MAILER_URLPATHS_EMAIL_CHANGE	string	URL path to use in the email change confirmation email. Defaults to /.
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.

Email Templates

Parameter	Type	Description
MAILER_TEMPLATES_INVITE	string	URL path to an email template to use when inviting a user. 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>

Parameter	Type	Description
MAILER_TEMPLATES_CONFIRMATION	string	URL path to an email template to use when confirming a signup. 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>

Parameter	Type	Description
MAILER_TEMPLATES_RECOVERY	string	URL path to an email template to use when resetting a password. 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>

Parameter	Type	Description
MAILER_TEMPLATES_MAGIC_LINK	string	URL path to an email template to use when sending magic link. 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>

Parameter	Type	Description
MAILER_TEMPLATES_EMAIL_CHANGE	string	URL path to an email template to use when confirming the change of an email address. 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

These options control the SMS-es sent from GoTrue.

Parameter	Type	Description
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. Valid otp lengths are between [6 - 10] digits
SMS_PROVIDER	string	Available options are: twilio, messagebird, textlocal, and vonage

If you're using twilio, you can obtain your credentials from the twilio dashboard:

You can find the SMS_TWILIO_ACCOUNT_SID and SMS_TWILIO_AUTH_TOKEN in the account info page of the twilio console dashboard.

Parameter	Type	Description
SMS_TWILIO_ACCOUNT_SID	string	Your twilio account string identifier (SID).
SMS_TWILIO_AUTH_TOKEN	string	Your twilio auth token.
SMS_TWILIO_MESSAGE_SERVICE_SID	string	Your twilio sender mobile number

If you're using MessageBird, you can obtain your credentials from the MessageBird dashboard:

Parameter	Type	Description
SMS_MESSAGEBIRD_ACCESS_KEY	string	Your MessageBird access key.
SMS_MESSAGEBIRD_ORIGINATOR	string	Your MessageBird sender phone number with + or company name.

Logging

Parameter	Type	Description
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.

Opentracing

Currently Datadog is the only tracer supported.

Parameter	Type	Description
TRACING_ENABLED	bool	Whether tracing is enabled or not. Defaults to false.
TRACING_HOST	string	The tracing destination. (e.g. GOTRUE_TRACING_HOST=127.0.0.1)
TRACING_PORT	int	The port for the tracing host.
TRACING_TAGS	string	A comma separated list of key:value pairs. These key value pairs will be added as tags to all opentracing spans. (e.g. GOTRUE_TRACING_TAGS="tag1:value1,tag2:value2")
SERVICE_NAME	string	The name to use for the service.

Webhooks

Parameter	Type	Description
WEBHOOK_URL	string	URL of the webhook receiver endpoint. This will be called when events like validate, signup or login occur.
WEBHOOK_SECRET	string	Shared secret to authorize webhook requests. This secret signs the JSON Web Signature of the request. You should use this to verify the integrity of the request. Otherwise others can feed your webhook receiver with fake data.
WEBHOOK_RETRIES	number	How often GoTrue should try a failed hook.
WEBHOOK_TIMEOUT_SEC	number	Time between retries (in seconds).
WEBHOOK_EVENTS	list	Which events should trigger a webhook. You can provide a comma separated list. For example to listen to all events, provide the values validate,signup,login.