--- id: about title: GoTrue 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. ## Configuration You may configure GoTrue using either a configuration file named `.env`, environment variables, or a combination of both. Environment variables are prefixed with `GOTRUE_`, and will always have precedence over values provided via file. ### Top-Level ``` GOTRUE_SITE_URL=https://example.netlify.com/ ``` `SITE_URL` - `string` **required** The base URL your site is located at. Currently used in combination with other settings to construct URLs used in emails. `OPERATOR_TOKEN` - `string` _Multi-instance mode only_ The shared secret with an operator (usually Netlify) for this microservice. Used to verify requests have been proxied through the operator and the payload values can be trusted. `DISABLE_SIGNUP` - `bool` When signup is disabled the only way to create new users is through invites. Defaults to `false`, all signups enabled. `GOTRUE_RATE_LIMIT_HEADER` - `string` Header on which to rate limit the `/token` endpoint. ### API ``` GOTRUE_API_HOST=localhost PORT=9999 ``` `API_HOST` - `string` Hostname to listen on. `PORT` (no prefix) / `API_PORT` - `number` Port number to listen on. Defaults to `8081`. `API_ENDPOINT` - `string` _Multi-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. ### Database ``` GOTRUE_DB_DRIVER=mysql DATABASE_URL=root@localhost/gotrue ``` `DB_DRIVER` - `string` **required** Chooses what dialect of database you want. Must be `mysql`. `DATABASE_URL` (no prefix) / `DB_DATABASE_URL` - `string` **required** 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 after you've built gotrue. - If built locally: `./gotrue migrate` - Using Docker: `docker run --rm gotrue gotrue migrate` ### Logging ``` 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 from `panic`, `fatal`, `error`, `warn`, `info`, or `debug`. Defaults to `info`. `LOG_FILE` - `string` If you wish logs to be written to a file, set `log_file` to a valid file path. ### JSON Web Tokens (JWT) ``` GOTRUE_JWT_SECRET=supersecretvalue GOTRUE_JWT_EXP=3600 GOTRUE_JWT_AUD=netlify ``` `JWT_SECRET` - `string` **required** 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 to `admin`. `JWT_DEFAULT_GROUP_NAME` - `string` The default group to assign all new users to. ### External Authentication Providers We support `bitbucket`, `github`, `gitlab`, and `google` for external authentication. Use the names as the keys underneath `external` to configure each separately. ``` GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=myappclientid GOTRUE_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` - `string` **required** The OAuth2 Client ID registered with the external provider. `EXTERNAL_X_SECRET` - `string` **required** The OAuth2 Client Secret provided by the external provider when you registered. `EXTERNAL_X_REDIRECT_URI` - `string` **required for gitlab** The URI a OAuth2 provider will redirect to with the `code` and `state` values. `EXTERNAL_X_URL` - `string` The base URL used for constructing the URLs to request authorization and access tokens. Used by `gitlab` only. Defaults to `https://gitlab.com`. ### E-Mail 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.com GOTRUE_SMTP_PORT=587 GOTRUE_SMTP_USER=smtp-delivery@example.com GOTRUE_SMTP_PASS=correcthorsebatterystaple GOTRUE_SMTP_ADMIN_EMAIL=support@example.com GOTRUE_MAILER_SUBJECTS_CONFIRMATION="Please confirm" ``` `SMTP_ADMIN_EMAIL` - `string` **required** The `From` email address for all emails sent. `SMTP_HOST` - `string` **required** The mail server hostname to send emails through. `SMTP_PORT` - `number` **required** 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 to `true`. Defaults to `false`. `MAILER_SECURE_EMAIL_CHANGE_ENABLED` - `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`. `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 to `You have been invited`. `MAILER_SUBJECTS_CONFIRMATION` - `string` Email subject to use for signup confirmation. Defaults to `Confirm Your Signup`. `MAILER_SUBJECTS_RECOVERY` - `string` Email subject to use for password reset. Defaults to `Reset Your Password`. `MAILER_SUBJECTS_MAGIC_LINK` - `string` Email subject to use for magic link email. Defaults to `Your Magic Link`. `MAILER_SUBJECTS_EMAIL_CHANGE` - `string` Email subject to use for email change confirmation. Defaults to `Confirm Email Change`. `MAILER_TEMPLATES_INVITE` - `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

You have been invited

You have been invited to create a user on {{ .SiteURL }}. Follow this link to accept the invite:

Accept the invite

``` `MAILER_TEMPLATES_CONFIRMATION` - `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

Confirm your signup

Follow this link to confirm your user:

Confirm your mail

``` `MAILER_TEMPLATES_RECOVERY` - `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

Reset Password

Follow this link to reset the password for your user:

Reset Password

``` `MAILER_TEMPLATES_MAGIC_LINK` - `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

Magic Link

Follow this link to login:

Log In

``` `MAILER_TEMPLATES_EMAIL_CHANGE` - `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

Confirm Change of Email

Follow this link to confirm the update of your email from {{ .Email }} to {{ .NewEmail }}:

Change Email

``` ## Endpoints GoTrue exposes the following endpoints: ### **GET /settings** Returns the publicly available settings for this gotrue instance. ```json { "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. ```json { "email": "email@example.com", "password": "secret" } ``` Returns: ```json { "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. This endpoint requires the `service_role` or `supabase_admin` JWT set as an Auth Bearer header: e.g. ```json headers: { "Authorization" : "Bearer eyJhbGciOiJI...M3A90LCkxxtX9oNP9KZO" } ``` ```json { "email": "email@example.com" } ``` Returns: ```json { "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 be `signup` or `recovery` or `invite` and the `token` is a token returned from either `/signup` or `/recover`. ```json { "type": "signup", "token": "confirmation-code-delivered-in-email" } ``` `password` is required for signup verification if no existing password exists. Returns: ```json { "access_token": "jwt-token-representing-the-user", "token_type": "bearer", "expires_in": 3600, "refresh_token": "a-refresh-token", "type": "signup | recovery | invite" } ``` ### **GET /verify** Verify a registration or a password recovery. Type can be `signup` or `recovery` or `magiclink` or `invite` and the `token` is a token returned from either `/signup` or `/recover` or `/magiclink`. query params: ```json { "type": "signup", "token": "confirmation-code-delivered-in-email" } ``` User will be logged in and redirected to: ```json SITE_URL/#access_token=jwt-token-representing-the-user&token_type=bearer&expires_in=3600&refresh_token=a-refresh-token&type=invite ``` Your app should detect the query params in the fragment and use them to set the session (supabase-js does this automatically) You can use the `type` param to redirect the user to a password set form in the case of `invite` or `recovery`, or show an account confirmed/welcome message in the case of `signup`, or direct them to some additional onboarding flow ### **POST /magiclink** Magic Link. Will deliver a link (e.g. `/verify?type=magiclink&token=fgtyuf68ddqdaDd`) to the user based on email address which they can use to redeem an access_token. By default Magic Links can only be sent once every 60 seconds ```json { "email": "email@example.com" } ``` Returns: ```json {} ``` when clicked the magic link will redirect the user to `#access_token=x&refresh_token=y&expires_in=z&token_type=bearer&type=magiclink` (see `/verify` above) ### **POST /recover** Password recovery. Will deliver a password recovery mail to the user based on email address. By default recovery links can only be sent once every 60 seconds ```json { "email": "email@example.com" } ``` Returns: ```json {} ``` ### **POST /token** This is an OAuth2 endpoint that currently implements the password and refresh_token grant types query params: ``` ?grant_type=password ``` body: ```json { "email": "name@domain.com", "password": "somepassword" } ``` or query params: ``` grant_type=refresh_token ``` body: ```json { "refresh_token": "a-refresh-token" } ``` Once you have an access token, you can access the methods requiring authentication by settings the `Authorization: Bearer YOUR_ACCESS_TOKEN_HERE` header. Returns: ```json { "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: ```json { "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, this method can be used to set custom user data. ```json { "email": "new-email@example.com", "password": "new-password", "data": { "key": "value", "number": 10, "admin": false } } ``` Returns: ```json { "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 /admin/users** Creates a new user. Requires your `service_role` API key and thus should only be used in secure server-side environments. ```json { "email": "new-email@example.com", "password": "new-password", "data": { "key": "value", "number": 10, "admin": false } } ``` Returns: ```json { "id": "11111111-2222-3333-4444-5555555555555", "aud": "authenticated", "role": "authenticated", "email": "email@example.com", "app_metadata": { "provider": "email" }, "user_metadata": null, "created_at": "2016-05-15T19:53:12.368652374-07:00", "updated_at": "2016-05-15T19:53:12.368652374-07:00" } ``` ### **GET /admin/users/{user_id}** Gets a user. Requires your `service_role` API key and thus should only be used in secure server-side environments. Returns: ```json { "id": "11111111-2222-3333-4444-5555555555555", "aud": "authenticated", "role": "authenticated", "email": "email@example.com", "app_metadata": { "provider": "email" }, "user_metadata": {}, "created_at": "2016-05-15T19:53:12.368652374-07:00", "updated_at": "2016-05-15T19:53:12.368652374-07:00" } ``` ### **PUT /admin/users/{user_id}** Updates a user. Requires your `service_role` API key and thus should only be used in secure server-side environments. ```json { "email": "email@example.com", "password": "updated-password", "data": { "key": "updated-value", "number": 10, "admin": false } } ``` Returns: ```json { "id": "11111111-2222-3333-4444-5555555555555", "aud": "authenticated", "role": "authenticated", "email": "email@example.com", "app_metadata": { "provider": "email" }, "user_metadata": {}, "created_at": "2016-05-15T19:53:12.368652374-07:00", "updated_at": "2016-05-15T19:53:12.368652374-07:00" } ``` ### **POST /admin/generate_link** Returns the corresponding email action link based on the type specified. The response also contains the query params of the action link as separate JSON fields for convenience (along with the email OTP from which the corresponding token is generated). Returns: ```js { "action_link": "http://localhost:9999/verify?token=TOKEN&type=TYPE&redirect_to=REDIRECT_URL", "email_otp": "EMAIL_OTP", "hashed_token": "TOKEN", "verification_type": "TYPE", "redirect_to": "REDIRECT_URL", ... } ``` ### **DELETE /admin/users/{user_id}** Deletes a user. Requires your `service_role` API key and thus should only be used in secure server-side environments. ### **POST /logout** Logout a user (Requires authentication). This will revoke all refresh tokens for the user. Remember that the JWT tokens will still be valid for stateless auth until they expires. ### **GET /authorize** Get access_token from external oauth provider query params: ``` provider=google | bitbucket | github | gitlab ``` Redirects to provider and then to `/callback` ### **GET /callback** External provider should redirect to here Redirects to `#access_token=&refresh_token=&expires_in=3600&provider=` ## Pre-built - [Docker](https://hub.docker.com/repository/docker/supabase/gotrue)