supabase/web/docs/reference/tools/auth.mdx

---
id: reference-auth
title: Auth Server
description: An SWT based API for managing users and issuing SWT tokens
---

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                |
| :-------- | :------- | :------------------------- |
| <span id="site_url">`SITE_URL`</span> | `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.). |
| <span id="uri_allow_list">`URI_ALLOW_LIST`</span> | `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 [ ].<br/><br/>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.)<br/><br/>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.)<br/>For more common glob patterns, check out the [following link](https://pkg.go.dev/github.com/gobwas/glob#Compile).|
| <span id="operator_token">`OPERATOR_TOKEN`</span> | `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. |
| <span id="disable_signup">`DISABLE_SIGNUP`</span> | `bool` | When signup is disabled the only way to create new users is through invites. Defaults to `false`, all signups enabled. |
| <span id="email_enabled">`EXTERNAL_EMAIL_ENABLED`</span> | `bool` | Use this to disable email signups (users can still use external oauth providers to sign up / sign in) |
| <span id="phone_enabled">`EXTERNAL_PHONE_ENABLED`</span> | `bool` | Use this to disable phone signups (users can still use external oauth providers to sign up / sign in) |
| <span id="rate_limit_token_refresh">`RATE_LIMIT_TOKEN_REFRESH`</span> | `string` | Rate limit the number of requests sent to `/token` |
| <span id="rate_limit_email_sent">`RATE_LIMIT_EMAIL_SENT`</span> | `string` | Rate limit the number of emails sent per hr on the following endpoints: `/signup`, `/invite`, `/magiclink`, `/recover`, `/otp`, & `/user`. |
| <span id="password_min_length">`PASSWORD_MIN_LENGTH`</span> | `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                |
| :-------- | :------- | :------------------------- |
| <span id="refresh_token_rotation_enabled">`REFRESH_TOKEN_ROTATION_ENABLED`</span> | `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. |
| <span id="refresh_token_reuse_interval">`REFRESH_TOKEN_REUSE_INTERVAL`</span> | `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.<br/>During the reuse interval, gotrue will not consider using a revoked token as a malicious attempt and will simply return the child refresh token.<br/>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. |
| <span id="captcha_enabled">`CAPTCHA_ENABLED`</span> | `string` | Enables the captcha middleware. |
| <span id="captcha_provider">`CAPTCHA_PROVIDER`</span> | `string` | The only captcha provider option supported is: `hcaptcha`. |
| <span id="captcha_secret">`CAPTCHA_SECRET`</span> | `string` | The captcha secret token. Retrieve this from your captcha account. |
| <span id="captcha_timeout">`CAPTCHA_TIMEOUT`</span> | `string` | The http timeout on the captcha request. |
| <span id="update_password_require_reauthentication">`UPDATE_PASSWORD_REQUIRE_REAUTHENTICATION`</span> | `bool` | When enabled, this requires a user to reauthenticate before being able to update their password. |

## API

| Parameter | Type     | Description                |
| :-------- | :------- | :------------------------- |
| <span id="api_host">`API_HOST`</span> | `string` | Hostname to listen on. |
| <span id="port">`PORT`</span> | `number` | Port number to listen on. Defaults to `8081`. |
| <span id="request_id_header">`REQUEST_ID_HEADER`</span> | `string` | If you wish to inherit a request ID from the incoming request, specify the name in this value. |


## Database

| Parameter | Type     | Description                |
| :-------- | :------- | :------------------------- |
| <span id="db_driver">`DB_DRIVER`</span> | `string` | **Required**. Chooses what dialect of database you want. Must be `postgres`. |
| <span id="database_url">`DATABASE_URL`</span> | `string` | **Required**. Connection string for the database. |
| <span id="db_max_pool_size">`DB_MAX_POOL_SIZE`</span> | `int` | Sets the maximum number of open connections to the database. Defaults to 0 which is equivalent to an "unlimited" number of connections. |
| <span id="db_namespace">`DB_NAMESPACE`</span> | `string` | Specifies the schema in which the tables are to be created in. |

## JSON Web Tokens (JWT)

| Parameter | Type     | Description                |
| :-------- | :------- | :------------------------- |
| <span id="jwt_secret">`JWT_SECRET`</span> | `string` | **Required**. The secret used to sign JWT tokens with. |
| <span id="jwt_exp">`JWT_EXP`</span> | `number` | How long tokens are valid for in seconds. Defaults to 3600 (1 hour). |
| <span id="jwt_aud">`JWT_AUD`</span> | `string` | The default JWT audience. Use audiences to group users. Defaults to `authenticated`. |
| <span id="jwt_admin_group_name">`JWT_ADMIN_GROUP_NAME`</span> | `string` | The name of the admin group (if enabled). Defaults to `admin`. |
| <span id="jwt_default_group_name">`JWT_DEFAULT_GROUP_NAME`</span> | `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                |
| :-------- | :------- | :------------------------- |
| <span id="external_x_enabled">`EXTERNAL_X_ENABLED`</span> | `bool` | Whether this external provider is enabled or not |
| <span id="external_x_client_id">`EXTERNAL_X_CLIENT_ID`</span> | `string` | **Required**. The OAuth2 Client ID registered with the external provider. |
| <span id="external_x_client_secret">`EXTERNAL_X_SECRET`</span> | `string` | **Required**. The OAuth2 Client Secret provided by the external provider when you registered. |
| <span id="external_x_redirect_uri">`EXTERNAL_X_REDIRECT_URI`</span> | `string` | **Required**. Also known as the callback url, this is the URI an OAuth2 provider will redirect to with the `code` and `state` values. |
| <span id="external_x_url">`EXTERNAL_X_URL`</span> | `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](https://www.freecodecamp.org/news/how-to-get-https-working-on-your-local-development-environment-in-5-minutes-7af615770eec/) for more information.
3. Generate the `GOTRUE_EXTERNAL_APPLE_SECRET` by following this [post](https://medium.com/identity-beyond-borders/how-to-configure-sign-in-with-apple-77c61e336003)!

## 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                |
| :-------- | :------- | :------------------------- |
| <span id="smtp_admin_email">`SMTP_ADMIN_EMAIL`</span> | `string` | **Required**. The `From` email address for all emails sent. |
| <span id="smtp_host">`SMTP_HOST`</span> | `string` | **Required**. The mail server hostname to send emails through. |
| <span id="smtp_port">`SMTP_PORT`</span> | `string` | **Required**. The port number to connect to the mail server on. |
| <span id="smtp_user">`SMTP_USER`</span> | `string` | **Required**. If the mail server requires authentication, the username to use. |
| <span id="smtp_pass">`SMTP_PASS`</span> | `string` | **Required**. If the mail server requires authentication, the password to use. |
| <span id="smtp_max_frequency">`SMTP_MAX_FREQUENCY`</span> | `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. |
| <span id="smtp_sender_name">`SMTP_SENDER_NAME`</span> | `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                |
| :-------- | :------- | :------------------------- |
| <span id="mailer_autoconfirm">`MAILER_AUTOCONFIRM`</span> | `bool` | If you do not require email confirmation, you may set this to `true`. Defaults to `false`. |
| <span id="mailer_secure_email_change_enabled">`MAILER_SECURE_EMAIL_CHANGE_ENABLED`</span> | `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`. |
| <span id="mailer_otp_exp">`MAILER_OTP_EXP`</span> | `string` | Controls the duration an email link or otp is valid for. Defaults to 24 hrs. |
| <span id="mailer_urlpaths_invite">`MAILER_URLPATHS_INVITE`</span> | `string` | URL path to use in the user invite email. Defaults to `/`. |
| <span id="mailer_urlpaths_confirmation">`MAILER_URLPATHS_CONFIRMATION`</span> | `string` | URL path to use in the signup confirmation email. Defaults to `/`. |
| <span id="mailer_urlpaths_recovery">`MAILER_URLPATHS_RECOVERY`</span> | `string` | URL path to use in the password reset email. Defaults to `/`. |
| <span id="mailer_urlpaths_email_change">`MAILER_URLPATHS_EMAIL_CHANGE`</span> | `string` | URL path to use in the email change confirmation email. Defaults to `/`. |
| <span id="mailer_subjects_invite">`MAILER_SUBJECTS_INVITE`</span> | `string` | Email subject to use for user invite. Defaults to `You have been invited`. |
| <span id="mailer_subjects_confirmation">`MAILER_SUBJECTS_CONFIRMATION`</span> | `string` | Email subject to use for signup confirmation. Defaults to `Confirm Your Signup`. |
| <span id="mailer_subjects_recovery">`MAILER_SUBJECTS_RECOVERY`</span> | `string` | Email subject to use for password reset. Defaults to `Reset Your Password`. |
| <span id="mailer_subjects_magiclink">`MAILER_SUBJECTS_MAGIC_LINK`</span> | `string` | Email subject to use for magic link email. Defaults to `Your Magic Link`. |
| <span id="mailer_subjects_email_change">`MAILER_SUBJECTS_EMAIL_CHANGE`</span> | `string` | Email subject to use for email change confirmation. Defaults to `Confirm Email Change`. |

## Email Templates

| Parameter | Type     | Description                |
| :-------- | :------- | :------------------------- |
| <span id="mailer_templates_invite">`MAILER_TEMPLATES_INVITE`</span> | `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):

```html 
<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                |
| :-------- | :------- | :------------------------- |
| <span id="mailer_templates_confirmation">`MAILER_TEMPLATES_CONFIRMATION`</span> | `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):

```html
<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                |
| :-------- | :------- | :------------------------- |
| <span id="mailer_templates_recovery">`MAILER_TEMPLATES_RECOVERY`</span> | `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):

```html
<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                |
| :-------- | :------- | :------------------------- |
| <span id="mailer_templates_magic_link">`MAILER_TEMPLATES_MAGIC_LINK`</span> | `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):

```html
<h2>Magic Link</h2>

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

| Parameter | Type     | Description                |
| :-------- | :------- | :------------------------- |
| <span id="mailer_templates_email_change">`MAILER_TEMPLATES_EMAIL_CHANGE`</span> | `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):

```html
<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                |
| :-------- | :------- | :------------------------- |
| <span id="sms_autoconfirm">`SMS_AUTOCONFIRM`</span> | `bool` | If you do not require phone confirmation, you may set this to `true`. Defaults to `false`. |
| <span id="sms_max_frequency">`SMS_MAX_FREQUENCY`</span> | `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)). |
| <span id="sms_otp_exp">`SMS_OTP_EXP`</span> | `number` | Controls the duration an sms otp is valid for. |
| <span id="sms_otp_length">`SMS_OTP_LENGTH`</span> | `number` | Controls the number of digits of the sms otp sent. Valid otp lengths are between [6 - 10] digits  |
| <span id="sms_provider">`SMS_PROVIDER`</span> | `string` | Available options are: `twilio`, `messagebird`, `textlocal`, and `vonage` |

If you're using twilio, you can obtain your credentials from the [twilio dashboard](https://www.twilio.com/docs/usage/requests-to-twilio#credentials):

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                |
| :-------- | :------- | :------------------------- |
| <span id="twilio_account_sid">`SMS_TWILIO_ACCOUNT_SID`</span> | `string` | Your twilio account string identifier (SID). |
| <span id="twilio_auth_token">`SMS_TWILIO_AUTH_TOKEN`</span> | `string` | Your twilio auth token.  |
| <span id="twilio_message_service_sid">`SMS_TWILIO_MESSAGE_SERVICE_SID`</span> | `string` | Your twilio sender mobile number |


If you're using MessageBird, you can obtain your credentials from the [MessageBird dashboard](https://dashboard.messagebird.com/en/developers/access):

| Parameter | Type     | Description                |
| :-------- | :------- | :------------------------- |
| <span id="messagebird_access_key">`SMS_MESSAGEBIRD_ACCESS_KEY`</span> | `string` | Your MessageBird access key. |
| <span id="messagebird_originator">`SMS_MESSAGEBIRD_ORIGINATOR`</span> | `string` | Your MessageBird sender phone number with + or company name.  |

## Logging

| Parameter | Type     | Description                |
| :-------- | :------- | :------------------------- |
| <span id="log_level">`LOG_LEVEL`</span> | `string` | Controls what log levels are output. Choose from `panic`, `fatal`, `error`, `warn`, `info`, or `debug`. Defaults to `info`. |
| <span id="log_file">`LOG_FILE`</span> | `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                |
| :-------- | :------- | :------------------------- |
| <span id="tracing_enabled">`TRACING_ENABLED`</span> | `bool` | Whether tracing is enabled or not. Defaults to `false`. |
| <span id="tracing_host">`TRACING_HOST`</span> | `string` | The tracing destination. (e.g. `GOTRUE_TRACING_HOST=127.0.0.1`) |
| <span id="tracing_port">`TRACING_PORT`</span> | `int` | The port for the tracing host. |
| <span id="tracing_tags">`TRACING_TAGS`</span> | `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"`) |
| <span id="service_name">`SERVICE_NAME`</span> | `string` | The name to use for the service. |

## Webhooks

| Parameter | Type     | Description                |
| :-------- | :------- | :------------------------- |
| <span id="webhook_url">`WEBHOOK_URL`</span> | `string` | URL of the webhook receiver endpoint. This will be called when events like `validate`, `signup` or `login` occur. |
| <span id="webhook_secret">`WEBHOOK_SECRET`</span> | `string` | Shared secret to authorize webhook requests. This secret signs the [JSON Web Signature](https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-41) of the request. You _should_ use this to verify the integrity of the request. Otherwise others can feed your webhook receiver with fake data. |
| <span id="webhook_retries">`WEBHOOK_RETRIES`</span> | `number` | How often GoTrue should try a failed hook. |
| <span id="webhook_timeout_sec">`WEBHOOK_TIMEOUT_SEC`</span> | `number` | Time between retries (in seconds). |
| <span id="webhook_events">`WEBHOOK_EVENTS`</span> | `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`. |