GoTrue requires a database connection. Currently, only mysql is supported.

• DB_DRIVER (string, required): Must be mysql.
• DATABASE_URL or DB_DATABASE_URL (string, required): Connection string for the database.
• DB_NAMESPACE (string): Prefix added to all table names.

Important: Migrations are not applied automatically. You must run them after building GoTrue.

GOTRUE_DB_DRIVER=mysql
DATABASE_URL=root@localhost/gotrue

Run migrations locally

./gotrue migrate

Run migrations using Docker

docker run --rm gotrue gotrue migrate

Use these settings to control the API server behavior:

• GOTRUE_API_HOST (string): Hostname to listen on.
• PORT or API_PORT (number): Port number to listen on. Defaults to 8081.
• GOTRUE_API_ENDPOINT (string): Multi-instance mode only. Controls the endpoint Netlify accesses.
• REQUEST_ID_HEADER (string): Specify the name of the header to inherit a request ID from.
• GOTRUE_API_EXPORT_SECRET (string): Secret used to allow exporting users for service migration.

GOTRUE_API_HOST=localhost
PORT=9999

Webhooks allow you to receive notifications for specific events:

• WEBHOOK_URL (string): The endpoint to receive webhook calls.
• WEBHOOK_SECRET (string): Shared secret used to sign the request (JSON Web Signature). Use this to verify request integrity.
• WEBHOOK_RETRIES (number): Number of retry attempts for failed hooks.
• WEBHOOK_TIMEOUT_SEC (number): Time between retries in seconds.
• WEBHOOK_EVENTS (list): Comma-separated list of events to trigger webhooks. Supported events: validate, signup, login, userdeleted, usermodified.

GoTrue supports bitbucket, github, gitlab, and google. For each provider X, configure the following:

• EXTERNAL_X_ENABLED (bool): Enables the provider.
• EXTERNAL_X_CLIENT_ID (string, required): OAuth2 Client ID.
• EXTERNAL_X_SECRET (string, required): OAuth2 Client Secret.
• EXTERNAL_X_REDIRECT_URI (string, required for gitlab): The URI for OAuth2 redirection.
• EXTERNAL_X_URL (string): Base URL for authorization/token requests. Used by gitlab only. Defaults to https://gitlab.com.

GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=myappclientid
GOTRUE_EXTERNAL_GITHUB_SECRET=clientsecretvaluessssh

Control the output verbosity and destination of logs:

• LOG_LEVEL (string): Log level. Options: panic, fatal, error, warn, info, or debug. Defaults to info. (Note: This variable does not use the GOTRUE_ prefix).
• GOTRUE_LOG_FILE (string): Path to a valid file where logs should be written.

LOG_LEVEL=debug
GOTRUE_LOG_FILE=/var/log/go/gotrue.log

Settings for signing and validating JWTs:

• JWT_SECRET (string, required): The secret used to sign tokens.
• JWT_EXP (number): Token validity duration in seconds. Defaults to 3600 (1 hour).
• JWT_AUD (string): Default JWT audience.
• JWT_ADMIN_GROUP_NAME (string): Name of the admin group. Defaults to admin.
• JWT_DEFAULT_GROUP_NAME (string): The default group assigned to all new users.

GOTRUE_JWT_SECRET=supersecretvalue
GOTRUE_JWT_EXP=3600
GOTRUE_JWT_AUD=netlify

GoTrue supports Datadog for tracing. Enable it using these settings:

• GOTRUE_TRACING_ENABLED (bool): Enables tracing. Defaults to false.
• GOTRUE_TRACING_HOST (string): The tracing destination host.
• GOTRUE_TRACING_PORT (number): The port for the tracing host.
• GOTRUE_TRACING_TAGS (string): Comma-separated list of key:value pairs to add to all spans.
• GOTRUE_SERVICE_NAME (string): The name of the service.

GOTRUE_TRACING_ENABLED=true
GOTRUE_TRACING_HOST=127.0.0.1
GOTRUE_TRACING_PORT=8126
GOTRUE_TRACING_TAGS="tag1:value1,tag2:value2"
GOTRUE_SERVICE_NAME="gotrue"

Use these settings for core service behavior:

• GOTRUE_SITE_URL (string, required): The base URL of your site. Used to construct email URLs.
• OPERATOR_TOKEN (string): Multi-instance mode only. Shared secret used to verify requests proxied through an operator.
• DISABLE_SIGNUP (bool): If true, new users can only be created via invites. Defaults to false.
• GOTRUE_RATE_LIMIT_HEADER (string): The header used to rate limit the /token endpoint.

GOTRUE_SITE_URL=https://example.netlify.com/

Register a new user by providing an email and password.

Request Body:

{
  "email": "email@example.com",
  "password": "secret"
}

Response: Returns the user object including id, email, confirmation_sent_at, created_at, and updated_at.

An OAuth2 endpoint that supports password, refresh_token, and authorization_code grant types.

Grant Types:

• password: grant_type=password&username=email@example.com&password=secret
• refresh_token: grant_type=refresh_token&refresh_token=my-refresh-token

Authentication: Once you have an access_token, include it in subsequent requests using the header: Authorization: Bearer YOUR_ACCESS_TOKEN_HERE.

Response: Returns an object with access_token, token_type, expires_in, and refresh_token.