An Elixir client for GoTrue.

GoTrue is an open source authentication service that supports many methods of authentication:

  • Classic email+password logins
  • Passwordless logins with magic links
  • OAUTH2 - Google, GitHub, BitBucket, GitLab, etc..



GoTrue is a way of doing authentication by delagating the work to a separate service. It has a very slim HTTP API, so less code to maintain. It's also a polyglot auth solution.

It was developed by Netlify, though this version is being developed against the supabase fork

For many apps, phx_gen_auth is a great solution, but it requires a bit more work to setup and adjust. It does mean inheriting a bunch of code. For a small team, or for quick experimentation, offloading a task like auth removes a big friction and reduces time to market.

It also makes it possibile to create an Elixir supabase client down the road.


Add gotrue to your list of dependencies in mix.exs:

def deps do
    {:gotrue, "~> 0.1.0"}


In your config/dev.exs & config/prod.exs, configure settings:

config :gotrue,
  # URL to your GoTrue instance
  base_url: "",

  # The project's API key
  api_key: "your-super-secret-operator-token"


Creating a user account

Several options exist to create an account:

Password based

Pass credentials to GoTrue.sign_up/1, a new account will be created and a JWT token is returned.

GoTrue.client("", "my-supabase-project-api-key")
|> GoTrue.sign_up(%{email: "", password: "123456"})


Oauth is performed on the client by redirecting the user. To get the redirection URL, call GoTrue.url_for_provider/1:


Users can login without password, by requesting a magic link:

GoTrue.client("", "my-supabase-project-api-key")
|> GoTrue.send_magic_link("")

That sends them an email with a link to login. The link will contain the access_token & refresh_token.

Sign in

If you're using password logins, sign in a user by passing the email & password to GoTrue.sign_in/1, it returns a JWT

GoTrue.client("", "my-supabase-project-api-key")
|> GoTrue.sign_in(%{email: "", password: "12345"})

Refreshing JWT

Each JWT expires based on your GoTrue server's settings. To refresh it, pass the refresh_token to GoTrue.refresh_access_token/1

# first get an access token, there are many ways:

# via sign up
%{access_token: jwt, refresh_token: refresh_token} = GoTrue.sign_up(...)

# or via login
%{access_token: jwt, refresh_token: refresh_token} = GoTrue.sign_in(...)

# or via a redirection from an oauth provider
def controller_action(conn, %{access_token: jwt, refresh_token: refresh_token}) do
  # put in session

# refresh it before it expires
%{access_token: new_jwt} = GoTrue.refresh_access_token(refresh_token)

Sign out

To revoke a JWT, call GoTrue.sign_out/1


Getting user info

The user's info can be accessed by calling GoTrue.get_user/1 with their current JWT:


Updating user info

Using a JWT, the user's data can be updated by calling GoTrue.update_user/2

GoTrue.update_user(jwt, %{data: %{favorite_language: "elixir"}})


Users can be invited by passing their email address to GoTrue.invite/1, this sends them an email with a completion link.

GoTrue.invite(%{email: ""})


To view the server's auth settings, call GoTrue.settings()