gotrue

An SWT based API for managing users and issuing SWT tokens.

3,828

284

3,828

View on GitHub View on NPM

Top Related Projects

auth

1,489

A JWT based API for managing users and issuing JWT tokens

logto

8,582

🧑‍🚀 The better identity infrastructure for developers and the open-source alternative to Auth0.

The most scalable and customizable identity server on the market. Replace your Homegrown, Auth0, Okta, Firebase with better UX and DX. Has all the tablestakes: Passkeys, Social Sign In, Multi-Factor Auth, SMS, SAML, TOTP, and more. Written in Go, cloud native, headless, API-first. Available as a service on Ory Network and for self-hosters.

keycloak

22,126

Open Source Identity and Access Management For Modern Applications and Services

zitadel

8,619

ZITADEL - Identity infrastructure, simplified for you.

authelia

21,425

The Single Sign-On Multi-Factor portal for web apps

Quick Overview

GoTrue is an open-source API for handling user authentication and registration for Jamstack applications. It provides a simple and secure way to manage user accounts, handle authentication, and integrate with various identity providers. GoTrue is designed to be used as a serverless function, making it easy to deploy and scale with Netlify or other cloud platforms.

Pros

Serverless Architecture: GoTrue is designed to be deployed as a serverless function, making it easy to scale and manage without the need for a dedicated server infrastructure.
Flexible Authentication: GoTrue supports a variety of authentication methods, including email/password, social providers (e.g., Google, GitHub), and custom identity providers.
Secure by Design: GoTrue uses industry-standard security practices, such as JWT-based authentication and encryption, to protect user data and prevent unauthorized access.
Easy Integration: GoTrue provides a simple and well-documented API, making it easy to integrate with a wide range of Jamstack applications.

Cons

Limited Features: While GoTrue provides a solid foundation for user authentication, it may lack some advanced features that some developers might require, such as multi-factor authentication or user management tools.
Dependency on Netlify: GoTrue was originally developed by Netlify and is primarily designed to work with Netlify's platform. This may limit its usefulness for developers who are not using Netlify or who require more flexibility in their deployment options.
Potential Learning Curve: Developers who are new to Jamstack or serverless architectures may need to invest some time in understanding the concepts and best practices associated with GoTrue and similar tools.
Limited Community Support: Compared to some more widely-used authentication solutions, GoTrue may have a smaller community of developers and a less extensive ecosystem of third-party integrations and resources.

Code Examples

Here are a few examples of how to use the GoTrue API:

Authenticating a User with Email and Password

const response = await fetch('/api/v1/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'mypassword'
  })
});

const { access_token, refresh_token } = await response.json();

Refreshing an Access Token

const response = await fetch('/api/v1/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    refresh_token: 'my_refresh_token'
  })
});

const { access_token, refresh_token } = await response.json();

Verifying a User's Email Address

const response = await fetch('/api/v1/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token: 'my_verification_token'
  })
});

const { user } = await response.json();

Updating a User's Profile

const response = await fetch('/api/v1/user', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer my_access_token'
  },
  body: JSON.stringify({
    email: 'new_email@example.com',
    full_name: 'New Name'
  })
});

const { user } = await response.json();

Getting Started

To get started with GoTrue, you can follow these steps:

Deploy GoTrue as a Serverless Function: GoTrue is designed to be deployed as a serverless function, which can be done using a platform like Netlify, AWS Lambda, or Google Cloud Functions. The GoTrue documentation provides detailed instructions for deploying the service.
Integrate GoTrue into Your Application: Once you have deployed GoTrue, you can integrate it into your Jamstack application by using the provided API. The [

Competitor Comparisons

auth

1,489

A JWT based API for managing users and issuing JWT tokens

Pros of Auth

More comprehensive authentication solution with built-in user management and role-based access control
Seamless integration with other Supabase services, providing a unified backend experience
Active development and frequent updates, with a growing community and ecosystem

Cons of Auth

Potentially more complex setup and configuration compared to GoTrue's simplicity
Tighter coupling with Supabase ecosystem, which may limit flexibility in some use cases
Less mature project with potential for more frequent breaking changes

Code Comparison

Auth:

const { data, error } = await supabase.auth.signUp({
  email: 'example@email.com',
  password: 'example-password',
})

GoTrue:

const user = await gotrue.signup({
  email: 'example@email.com',
  password: 'example-password',
})

Both libraries offer similar functionality for user authentication, but Auth provides a more integrated approach within the Supabase ecosystem. GoTrue focuses on simplicity and can be used as a standalone service, while Auth is designed to work seamlessly with other Supabase components. The choice between the two depends on project requirements, desired level of integration, and preference for simplicity versus comprehensive features.

logto

8,582

🧑‍🚀 The better identity infrastructure for developers and the open-source alternative to Auth0.

Pros of Logto

More comprehensive authentication solution with built-in user management and OIDC support
Offers a user-friendly admin console for easier configuration and management
Supports multiple languages and frameworks out of the box

Cons of Logto

Larger codebase and potentially more complex setup compared to GoTrue
May have a steeper learning curve for developers new to authentication systems
Less focused on serverless deployments, which is a strength of GoTrue

Code Comparison

GoTrue (JavaScript):

const gotrue = new GoTrue({
  APIUrl: 'https://example.netlify.com/.netlify/identity',
  audience: '',
  setCookie: false,
});

const user = await gotrue.login(email, password);

Logto (JavaScript):

import LogtoClient from '@logto/browser';

const logto = new LogtoClient({
  endpoint: 'https://example.logto.app',
  appId: 'app-id',
});

await logto.signIn('http://localhost:3000/callback');

Both repositories provide authentication solutions, but Logto offers a more feature-rich platform with built-in user management and OIDC support. GoTrue, on the other hand, is more lightweight and focused on serverless deployments, making it potentially easier to integrate into Netlify-based projects. The code examples demonstrate the different approaches to authentication, with Logto using a more modern, promise-based API.

kratos

11,181

Pros of Kratos

More comprehensive identity and user management system
Supports multiple authentication methods (passwords, social logins, WebAuthn)
Highly customizable and extensible architecture

Cons of Kratos

Steeper learning curve due to its complexity
Requires more setup and configuration compared to GoTrue
May be overkill for simpler authentication needs

Code Comparison

Kratos (API request for user registration):

import "github.com/ory/kratos-client-go"

client := kratos.NewAPIClient(kratos.NewConfiguration())
flow, _, err := client.V0alpha2Api.InitializeSelfServiceRegistrationFlowWithoutBrowser(context.Background())

GoTrue (User registration):

import "github.com/netlify/gotrue-go"

client := gotrue.NewClient("YOUR_GOTRUE_URL")
user, err := client.Signup("user@example.com", "password123", nil)

Both Kratos and GoTrue are authentication and user management solutions, but they differ in scope and complexity. Kratos offers a more comprehensive identity management system with advanced features, while GoTrue provides a simpler, more straightforward authentication solution. The choice between the two depends on the specific requirements of your project and the level of customization and features needed.

keycloak

22,126

Open Source Identity and Access Management For Modern Applications and Services

Pros of Keycloak

More comprehensive identity and access management solution with advanced features like user federation, identity brokering, and social login
Highly customizable and extensible through themes, plugins, and custom providers
Supports a wide range of protocols including OpenID Connect, SAML, and OAuth 2.0

Cons of Keycloak

Steeper learning curve and more complex setup compared to GoTrue
Requires more resources to run and maintain, potentially overkill for smaller projects
Less seamless integration with Netlify's ecosystem and services

Code Comparison

GoTrue (JavaScript):

const gotrue = new GoTrue({
  APIUrl: 'https://example.netlify.com/.netlify/identity',
  audience: '',
  setCookie: false,
});

const user = await gotrue.signup(email, password);

Keycloak (Java):

Keycloak keycloak = KeycloakBuilder.builder()
    .serverUrl("http://localhost:8080/auth")
    .realm("myrealm")
    .clientId("myclient")
    .clientSecret("secret")
    .build();

keycloak.realm("myrealm").users().create(userRepresentation);

Both repositories provide authentication and user management capabilities, but Keycloak offers a more robust and feature-rich solution suitable for enterprise-level applications. GoTrue, on the other hand, is more lightweight and integrates seamlessly with Netlify's services, making it ideal for smaller projects or those already using Netlify's ecosystem.

zitadel

8,619

ZITADEL - Identity infrastructure, simplified for you.

Pros of Zitadel

More comprehensive identity and access management solution
Supports multiple authentication protocols (OIDC, OAuth, SAML)
Offers advanced features like multi-factor authentication and passwordless login

Cons of Zitadel

More complex setup and configuration compared to GoTrue
Steeper learning curve due to its extensive feature set
May be overkill for simple authentication needs

Code Comparison

GoTrue (authentication endpoint):

func (ts *GoTrueServer) signupHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    instanceID := getInstanceID(ctx)
    params := &SignupParams{}
    jsonDecoder := json.NewDecoder(r.Body)
    err := jsonDecoder.Decode(params)
    if err != nil {
        BadRequestError(w, fmt.Sprintf("Could not read signup params: %v", err))
        return
    }
}

Zitadel (authentication endpoint):

func (h *Handler) HandleAuthentication(w http.ResponseWriter, r *http.Request) {
    ctx, span := tracing.NewSpan(r.Context())
    defer span.End()
    authRequest, err := h.authRepo.CreateAuthRequest(ctx, domain.AuthRequestTypeLogin)
    if err != nil {
        h.renderError(w, r, err)
        return
    }
    http.Redirect(w, r, authRequest.LoginURL(), http.StatusFound)
}

Both repositories provide authentication functionality, but Zitadel offers a more comprehensive solution with additional features and protocols. GoTrue is simpler and easier to set up for basic authentication needs, while Zitadel provides more advanced capabilities at the cost of increased complexity.

authelia

21,425

The Single Sign-On Multi-Factor portal for web apps

Pros of Authelia

More comprehensive authentication solution with multi-factor authentication (MFA) support
Self-hosted and open-source, offering greater control and customization
Integrates with various backends and supports multiple identity providers

Cons of Authelia

More complex setup and configuration compared to GoTrue
Requires self-hosting, which may increase maintenance overhead
Less suitable for simple authentication needs in serverless environments

Code Comparison

Authelia (configuration example):

jwt_secret: a_very_important_secret
default_redirection_url: https://public.example.com
server:
  host: 0.0.0.0
  port: 9091

GoTrue (configuration example):

API_HOST = "0.0.0.0"
PORT = 8081
JWT_SECRET = "CHANGE-THIS!"
DB_DRIVER = "sqlite3"
DB_DATABASE_URL = "gotrue.db"

Summary

Authelia is a more feature-rich, self-hosted authentication solution suitable for complex scenarios, while GoTrue is a simpler, API-driven option that integrates well with serverless architectures. Authelia offers greater control and customization but requires more setup and maintenance. GoTrue provides an easier setup process and is well-suited for Netlify-based projects but may lack some advanced features found in Authelia.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

GoTrue

User management for APIs

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 Jamstack 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.

Opentracing

Currently, only the Datadog tracer is supported.

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"

TRACING_ENABLED - bool

Whether tracing is enabled or not. Defaults to false.

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.

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_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_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):

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

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):

<h2>Confirm your signup</h2>

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

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):

<h2>Reset Password</h2>

<p>Follow this link to reset the password for your user:</p>
<p><a href="{{ .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, and ConfirmationURL 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><a href="{{ .ConfirmationURL }}">Change Email</a></p>

WEBHOOK_URL - string

Url of the webhook receiver endpoint. This will be called when events like validate, signup or login occur.

WEBHOOK_SECRET - string

Shared secret to authorize webhook requests. This secret signs the JSON Web Signature of the request. You should 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 values validate,signup,login.

Endpoints

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

{
  "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 be signup or recovery and the token 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 on email address.
```
{
  "email": "email@example.com"
}
```
Returns:
```
{}
```
POST /token

This is an OAuth2 endpoint that currently implements the 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 authentication by settings the Authorization: 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, this method 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 tokens will still be valid for stateless auth until they expire.

TODO

Schema for custom user data in config file

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of Auth

Cons of Auth

Code Comparison

Pros of Logto

Cons of Logto

Code Comparison

Pros of Kratos

Cons of Kratos

Code Comparison

Pros of Keycloak

Cons of Keycloak

Code Comparison

Pros of Zitadel

Cons of Zitadel

Code Comparison

Pros of Authelia

Cons of Authelia

Code Comparison

Summary

Convert designs to code with AI

README

Configuration

Top-Level

API

Database

Logging

Opentracing

JSON Web Tokens (JWT)

External Authentication Providers

E-Mail

Endpoints

TODO

Top Related Projects

Convert designs to code with AI

NPM DownloadsLast 30 Days