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 a small open-source API written in golang, that can act as a self-standing
API service for handling user registration and authentication for JAM projects.

It's based on OAuth2 and JWT and will handle user signup, authentication and custom
user data. 

If you're using gotrue on the Supabase platform, some of these options are not exposed on the dashboard as they are set internally.
If you're self-hosting gotrue on your own infrastructure, you will need to maintain these configuration options in an `.env` file. Most of these configuration options need to be prefixed with `GOTRUE_` if self-hosting.

## Configuration

The following list provides an overview of the configuration set in gotrue.

### 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 ngrok or another proxy.
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_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, only the Datadog tracer is 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`. |