Repository files navigation

User management for APIs

GoTrue is a small open-source API written in Golang, that can act as a self-standingAPI service for handling user registration and authentication for Jamstack projects.

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

You may configure GoTrue using either a configuration file named.env,environment variables, or a combination of both. Environment variables are prefixed withGOTRUE_, and will always have precedence over values provided via file.

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

SITE_URL -stringrequired

The base URL your site is located at. Currently used in combination with other settings to construct URLs used in emails.

OPERATOR_TOKEN -stringMulti-instance mode only

The shared secret with an operator (usually Netlify) for this microservice. Used to verify requests have been proxied through the operator andthe payload values can be trusted.

DISABLE_SIGNUP -bool

When signup is disabled the only way to create new users is through invites. Defaults tofalse, all signups enabled.

GOTRUE_RATE_LIMIT_HEADER -string

Header on which to rate limit the/token endpoint.

GOTRUE_API_HOST=localhostPORT=9999

API_HOST -string

Hostname to listen on.

PORT (no prefix) /API_PORT -number

Port number to listen on. Defaults to8081.

API_ENDPOINT -stringMulti-instance mode only

Controls what endpoint Netlify can access this API on.

REQUEST_ID_HEADER -string

If you wish to inherit a request ID from the incoming request, specify the name in this value.

GOTRUE_DB_DRIVER=mysqlDATABASE_URL=root@localhost/gotrue

DB_DRIVER -stringrequired

Chooses what dialect of database you want. Must bemysql.

DATABASE_URL (no prefix) /DB_DATABASE_URL -stringrequired

Connection string for the database.

DB_NAMESPACE -string

Adds a prefix to all table names.

Migrations Note

Migrations are not applied automatically, so you will need to run them afteryou've built gotrue.

• If built locally:./gotrue migrate
• Using Docker:docker run --rm gotrue gotrue migrate

LOG_LEVEL=debug# available without GOTRUE prefix (exception)GOTRUE_LOG_FILE=/var/log/go/gotrue.log

LOG_LEVEL -string

Controls what log levels are output. Choose frompanic,fatal,error,warn,info, ordebug. Defaults toinfo.

LOG_FILE -string

If you wish logs to be written to a file, setlog_file to a valid file path.

Currently, only the Datadog tracer is supported.

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

TRACING_ENABLED -bool

Whether tracing is enabled or not. Defaults tofalse.

TRACING_HOST -bool

The tracing destination.

TRACING_PORT -bool

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.

SERVICE_NAME -string

The name to use for the service.

GOTRUE_JWT_SECRET=supersecretvalueGOTRUE_JWT_EXP=3600GOTRUE_JWT_AUD=netlify

JWT_SECRET -stringrequired

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.

JWT_ADMIN_GROUP_NAME -string

The name of the admin group (if enabled). Defaults toadmin.

JWT_DEFAULT_GROUP_NAME -string

The default group to assign all new users to.

We supportbitbucket,github,gitlab, andgoogle for external authentication.Use the names as the keys underneathexternal to configure each separately.

GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=myappclientidGOTRUE_EXTERNAL_GITHUB_SECRET=clientsecretvaluessssh

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

EXTERNAL_X_ENABLED -bool

Whether this external provider is enabled or not

EXTERNAL_X_CLIENT_ID -stringrequired

The OAuth2 Client ID registered with the external provider.

EXTERNAL_X_SECRET -stringrequired

The OAuth2 Client Secret provided by the external provider when you registered.

EXTERNAL_X_REDIRECT_URI -stringrequired for gitlab

The URI a OAuth2 provider will redirect to with thecode andstate values.

EXTERNAL_X_URL -string

The base URL used for constructing the URLs to request authorization and access tokens. Used bygitlab only. Defaults tohttps://gitlab.com.

Sending email is not required, but highly recommended for password recovery.If enabled, you must provide the required values below.

GOTRUE_SMTP_HOST=smtp.mandrillapp.comGOTRUE_SMTP_PORT=587GOTRUE_SMTP_USER=smtp-delivery@example.comGOTRUE_SMTP_PASS=correcthorsebatterystapleGOTRUE_SMTP_ADMIN_EMAIL=support@example.comGOTRUE_MAILER_SUBJECTS_CONFIRMATION="Please confirm"

SMTP_ADMIN_EMAIL -stringrequired

TheFrom email address for all emails sent.

SMTP_HOST -stringrequired

The mail server hostname to send emails through.

SMTP_PORT -numberrequired

The port number to connect to the mail server on.

SMTP_USER -string

If the mail server requires authentication, the username to use.

SMTP_PASS -string

If the mail server requires authentication, the password to use.

SMTP_MAX_FREQUENCY -number

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 900 (15 minutes).

MAILER_AUTOCONFIRM -bool

If you do not require email confirmation, you may set this totrue. Defaults tofalse.

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 toYou have been invited.

MAILER_SUBJECTS_CONFIRMATION -string

Email subject to use for signup confirmation. Defaults toConfirm Your Signup.

MAILER_SUBJECTS_RECOVERY -string

Email subject to use for password reset. Defaults toReset Your Password.

MAILER_SUBJECTS_EMAIL_CHANGE -string

Email subject to use for email change confirmation. Defaults toConfirm Email Change.

MAILER_TEMPLATES_INVITE -string

URL path to an email template to use when inviting a user.SiteURL,Email, andConfirmationURL 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><ahref="{{ .ConfirmationURL }}">Accept the invite</a></p>

MAILER_TEMPLATES_CONFIRMATION -string

URL path to an email template to use when confirming a signup.SiteURL,Email, andConfirmationURL variables are available.

Default Content (if template is unavailable):

<h2>Confirm your signup</h2><p>Follow this link to confirm your user:</p><p><ahref="{{ .ConfirmationURL }}">Confirm your mail</a></p>

MAILER_TEMPLATES_RECOVERY -string

URL path to an email template to use when resetting a password.SiteURL,Email, andConfirmationURL 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><ahref="{{ .ConfirmationURL }}">Reset Password</a></p>

MAILER_TEMPLATES_EMAIL_CHANGE -string

URL path to an email template to use when confirming the change of an email address.SiteURL,Email,NewEmail, andConfirmationURL 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><ahref="{{ .ConfirmationURL }}">Change Email</a></p>

WEBHOOK_URL -string

Url of the webhook receiver endpoint. This will be called when events likevalidate,signup orlogin occur.

WEBHOOK_SECRET -string

Shared secret to authorize webhook requests. This secret signs theJSON Web Signature of the request. Youshould 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 valuesvalidate,signup,login.

GoTrue exposes the following endpoints:

• GET /settings

  Returns the publicly available settings for this gotrue instance.

  {"external": {"bitbucket":true,"github":true,"gitlab":true,"google":true  },"disable_signup":false,"autoconfirm":false}

• POST /signup

  Register a new user with an email and password.

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

  Returns:

  {"id":"11111111-2222-3333-4444-5555555555555","email":"email@example.com","confirmation_sent_at":"2016-05-15T20:49:40.882805774-07:00","created_at":"2016-05-15T19:53:12.368652374-07:00","updated_at":"2016-05-15T19:53:12.368652374-07:00"}

• POST /invite

  Invites a new user with an email.

  {"email":"email@example.com"}

  Returns:

  {"id":"11111111-2222-3333-4444-5555555555555","email":"email@example.com","confirmation_sent_at":"2016-05-15T20:49:40.882805774-07:00","created_at":"2016-05-15T19:53:12.368652374-07:00","updated_at":"2016-05-15T19:53:12.368652374-07:00","invited_at":"2016-05-15T19:53:12.368652374-07:00"}

• POST /verify

  Verify a registration or a password recovery. Type can besignup orrecoveryand thetoken is a token returned from either/signup or/recover.

  {"type":"signup","token":"confirmation-code-delivered-in-email","password":"12345abcdef"}

  password is required for signup verification if no existing password exists.

  Returns:

  {"access_token":"jwt-token-representing-the-user","token_type":"bearer","expires_in":3600,"refresh_token":"a-refresh-token"}

• POST /recover

  Password recovery. Will deliver a password recovery mail to the user based onemail address.

  {"email":"email@example.com"}

  Returns:

  {}

• POST /token

  This is an OAuth2 endpoint that currently implementsthe password, refresh_token, and authorization_code grant types

  grant_type=password&username=email@example.com&password=secret

  or

  grant_type=refresh_token&refresh_token=my-refresh-token

  Once you have an access token, you can access the methods requiring authenticationby settings theAuthorization: Bearer YOUR_ACCESS_TOKEN_HERE header.

  Returns:

  {"access_token":"jwt-token-representing-the-user","token_type":"bearer","expires_in":3600,"refresh_token":"a-refresh-token"}

• GET /user

  Get the JSON object for the logged in user (requires authentication)

  Returns:

  {"id":"11111111-2222-3333-4444-5555555555555","email":"email@example.com","confirmation_sent_at":"2016-05-15T20:49:40.882805774-07:00","created_at":"2016-05-15T19:53:12.368652374-07:00","updated_at":"2016-05-15T19:53:12.368652374-07:00"}

• PUT /user

  Update a user (Requires authentication). Apart from changing email/password, thismethod can be used to set custom user data.

  {"email":"new-email@example.com","password":"new-password","data": {"key":"value","number":10,"admin":false  }}

  Returns:

  {"id":"11111111-2222-3333-4444-5555555555555","email":"email@example.com","confirmation_sent_at":"2016-05-15T20:49:40.882805774-07:00","created_at":"2016-05-15T19:53:12.368652374-07:00","updated_at":"2016-05-15T19:53:12.368652374-07:00"}

• POST /logout

  Logout a user (Requires authentication).

  This will revoke all refresh tokens for the user. Remember that the JWT tokenswill still be valid for stateless auth until they expire.

• Schema for custom user data in config file