Skip to main content

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

ParameterTypeDescription
SITE_URLstringRequired. 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_LISTstringA 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_TOKENstringThe 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_SIGNUPboolWhen signup is disabled the only way to create new users is through invites. Defaults to false, all signups enabled.
EXTERNAL_EMAIL_ENABLEDboolUse this to disable email signups (users can still use external oauth providers to sign up / sign in)
EXTERNAL_PHONE_ENABLEDboolUse this to disable phone signups (users can still use external oauth providers to sign up / sign in)
RATE_LIMIT_TOKEN_REFRESHstringRate limit the number of requests sent to /token
RATE_LIMIT_EMAIL_SENTstringRate limit the number of emails sent per hr on the following endpoints: /signup, /invite, /magiclink, /recover, /otp, & /user.
PASSWORD_MIN_LENGTHintMinimum 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_ .

ParameterTypeDescription
REFRESH_TOKEN_ROTATION_ENABLEDboolIf 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_INTERVALstringThis 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_ENABLEDstringEnables the captcha middleware.
CAPTCHA_PROVIDERstringThe only captcha provider option supported is: hcaptcha.
CAPTCHA_SECRETstringThe captcha secret token. Retrieve this from your captcha account.
CAPTCHA_TIMEOUTstringThe http timeout on the captcha request.
UPDATE_PASSWORD_REQUIRE_REAUTHENTICATIONboolWhen enabled, this requires a user to reauthenticate before being able to update their password.

API

ParameterTypeDescription
API_HOSTstringHostname to listen on.
PORTnumberPort number to listen on. Defaults to 8081.
REQUEST_ID_HEADERstringIf you wish to inherit a request ID from the incoming request, specify the name in this value.

Database

ParameterTypeDescription
DB_DRIVERstringRequired. Chooses what dialect of database you want. Must be postgres.
DATABASE_URLstringRequired. Connection string for the database.
DB_MAX_POOL_SIZEintSets the maximum number of open connections to the database. Defaults to 0 which is equivalent to an "unlimited" number of connections.
DB_NAMESPACEstringSpecifies the schema in which the tables are to be created in.

JSON Web Tokens (JWT)

ParameterTypeDescription
JWT_SECRETstringRequired. The secret used to sign JWT tokens with.
JWT_EXPnumberHow long tokens are valid for in seconds. Defaults to 3600 (1 hour).
JWT_AUDstringThe default JWT audience. Use audiences to group users. Defaults to authenticated.
JWT_ADMIN_GROUP_NAMEstringThe name of the admin group (if enabled). Defaults to admin.
JWT_DEFAULT_GROUP_NAMEstringThe 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.

ParameterTypeDescription
EXTERNAL_X_ENABLEDboolWhether this external provider is enabled or not
EXTERNAL_X_CLIENT_IDstringRequired. The OAuth2 Client ID registered with the external provider.
EXTERNAL_X_SECRETstringRequired. The OAuth2 Client Secret provided by the external provider when you registered.
EXTERNAL_X_REDIRECT_URIstringRequired. Also known as the callback url, this is the URI an OAuth2 provider will redirect to with the code and state values.
EXTERNAL_X_URLstringThe 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.

ParameterTypeDescription
SMTP_ADMIN_EMAILstringRequired. The From email address for all emails sent.
SMTP_HOSTstringRequired. The mail server hostname to send emails through.
SMTP_PORTstringRequired. The port number to connect to the mail server on.
SMTP_USERstringRequired. If the mail server requires authentication, the username to use.
SMTP_PASSstringRequired. If the mail server requires authentication, the password to use.
SMTP_MAX_FREQUENCYstringControls 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_NAMEstringSets the name of the sender. Defaults to the SMTP_ADMIN_EMAIL if not used.

Email

These options control the emails sent from GoTrue.

ParameterTypeDescription
MAILER_AUTOCONFIRMboolIf you do not require email confirmation, you may set this to true. Defaults to false.
MAILER_OTP_EXPstringControls the duration an email link or otp is valid for. Defaults to 24 hrs.
MAILER_URLPATHS_INVITEstringURL path to use in the user invite email. Defaults to /.
MAILER_URLPATHS_CONFIRMATIONstringURL path to use in the signup confirmation email. Defaults to /.
MAILER_URLPATHS_RECOVERYstringURL path to use in the password reset email. Defaults to /.
MAILER_URLPATHS_EMAIL_CHANGEstringURL path to use in the email change confirmation email. Defaults to /.
MAILER_SUBJECTS_INVITEstringEmail subject to use for user invite. Defaults to You have been invited.
MAILER_SUBJECTS_CONFIRMATIONstringEmail subject to use for signup confirmation. Defaults to Confirm Your Signup.
MAILER_SUBJECTS_RECOVERYstringEmail subject to use for password reset. Defaults to Reset Your Password.
MAILER_SUBJECTS_MAGIC_LINKstringEmail subject to use for magic link email. Defaults to Your Magic Link.
MAILER_SUBJECTS_EMAIL_CHANGEstringEmail subject to use for email change confirmation. Defaults to Confirm Email Change.

Email Templates

ParameterTypeDescription
MAILER_TEMPLATES_INVITEstringURL 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>
ParameterTypeDescription
MAILER_TEMPLATES_CONFIRMATIONstringURL 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>
ParameterTypeDescription
MAILER_TEMPLATES_RECOVERYstringURL 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>
ParameterTypeDescription
MAILER_TEMPLATES_MAGIC_LINKstringURL 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>
ParameterTypeDescription
MAILER_TEMPLATES_EMAIL_CHANGEstringURL 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.

ParameterTypeDescription
SMS_AUTOCONFIRMboolIf you do not require phone confirmation, you may set this to true. Defaults to false.
SMS_MAX_FREQUENCYnumberControls 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_EXPnumberControls the duration an sms otp is valid for.
SMS_OTP_LENGTHnumberControls the number of digits of the sms otp sent. Valid otp lengths are between [6 - 10] digits
SMS_PROVIDERstringAvailable 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.

ParameterTypeDescription
SMS_TWILIO_ACCOUNT_SIDstringYour twilio account string identifier (SID).
SMS_TWILIO_AUTH_TOKENstringYour twilio auth token.
SMS_TWILIO_MESSAGE_SERVICE_SIDstringYour twilio sender mobile number

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

ParameterTypeDescription
SMS_MESSAGEBIRD_ACCESS_KEYstringYour MessageBird access key.
SMS_MESSAGEBIRD_ORIGINATORstringYour MessageBird sender phone number with + or company name.

Logging

ParameterTypeDescription
LOG_LEVELstringControls what log levels are output. Choose from panic, fatal, error, warn, info, or debug. Defaults to info.
LOG_FILEstringIf 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.

ParameterTypeDescription
TRACING_ENABLEDboolWhether tracing is enabled or not. Defaults to false.
TRACING_HOSTstringThe tracing destination. (e.g. GOTRUE_TRACING_HOST=127.0.0.1)
TRACING_PORTintThe port for the tracing host.
TRACING_TAGSstringA 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_NAMEstringThe name to use for the service.

Webhooks

ParameterTypeDescription
WEBHOOK_URLstringURL of the webhook receiver endpoint. This will be called when events like validate, signup or login occur.
WEBHOOK_SECRETstringShared 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_RETRIESnumberHow often GoTrue should try a failed hook.
WEBHOOK_TIMEOUT_SECnumberTime between retries (in seconds).
WEBHOOK_EVENTSlistWhich 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.