Tokens provide a way to generate and verify bearer tokens for use in Channels or API authentication.

The data can be read by clients, but the message is signed to prevent tampering.

Basic Usage

When generating a unique token for usage in an API or Channel it is advised to use a unique identifier for the user typically the id from a database. For example:

iex> user_id = 1
iex> token = Phoenix.Token.sign(endpoint, "user", user_id)
iex> Phoenix.Token.verify(endpoint, "user", token)
{:ok, 1}

In that example we have a user’s id, we generate a token and send it to the client. We could send it to the client in multiple ways. One is via the meta tag:

<%= tag :meta, name: "channel_token",
               content: Phoenix.Token.sign(@conn, "user", @current_user.id) %>

Or an endpoint that returns it:

def create(conn, params) do
  user = User.create(params)
  render conn, "user.json",
         %{token: Phoenix.Token.sign(conn, "user", user.id), user: user}
end

When using it with a socket a typical example might be:

defmodule MyApp.UserSocket do
  use Phoenix.Socket

  def connect(%{"token" => token}, socket) do
    # Max age of 2 weeks (1209600 seconds)
    case Phoenix.Token.verify(socket, "user", token, max_age: 1209600) do
      {:ok, user_id} ->
        socket = assign(socket, :user, Repo.get!(User, user_id))
        {:ok, socket}
      {:error, _} ->
        :error
    end
  end
end

In this example the phoenix.js client will be sending up the token in the connect command.

Phoenix.Token can also be used for validating APIs, handling password resets, e-mail confirmation and more.