Phoenix.Token

Parsed documentation:
View on GitHub
Tokens provide a way to generate and verify bearer
tokens for use in Channels or API authentication.

The data stored in the token is signed to prevent tampering
but not encrypted. This means it is safe to store identification
information (such as user IDs) but should not be used to store
confidential information (such as credit card numbers).

## Example

When generating a unique token for use 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(MyApp.Endpoint, "user salt", user_id)
    iex> Phoenix.Token.verify(MyApp.Endpoint, "user salt", token, max_age: 86400)
    {:ok, 1}

In that example we have a user's id, we generate a token and
verify it using the secret key base configured in the given
`endpoint`. We guarantee the token will only be valid for one day
by setting a max age (recommended).

The first argument to both `sign/4` and `verify/4` can be one of:

  * the module name of a Phoenix endpoint (shown above) - where
    the secret key base is extracted from the endpoint
  * `Plug.Conn` - where the secret key base is extracted from the
    endpoint stored in the connection
  * `Phoenix.Socket` - where the secret key base is extracted from
    the endpoint stored in the socket
  * a string, representing the secret key base itself. A key base
    with at least 20 randomly generated characters should be used
    to provide adequate entropy

The second argument is a [cryptographic salt](https://en.wikipedia.org/wiki/Salt_(cryptography))
which must be the same in both calls to `sign/4` and `verify/4`.
For instance, it may be called "user auth" when generating a token
that will be used to authenticate users on channels or on your APIs.

The third argument can be any term (string, int, list, etc.)
that you wish to codify into the token. Upon valid verification,
this same term will be extracted from the token.

## Usage

Once a token is signed, we can 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 salt", @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 salt", user.id), user: user})
    end

Once the token is sent, the client may now send it back to the server
as an authentication mechanism. For example, we can use it to authenticate
a user on a Phoenix channel:

    defmodule MyApp.UserSocket do
      use Phoenix.Socket

      def connect(%{"token" => token}, socket) do
        case Phoenix.Token.verify(socket, "user salt", token, max_age: 86400) 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 send the token in the
`connect` command which is then validated by the server.

`Phoenix.Token` can also be used for validating APIs, handling
password resets, e-mail confirmation and more.
No suggestions.
Please help! Open an issue on GitHub if this assessment is incorrect.