Elixir & Phoenix with the X API v2: An OAuth 2.0 Refresh

defmodule App.X do
  @moduledoc """
  Minimal client for the X API v2, authenticated via
  OAuth 2.0 Authorization Code + PKCE.
  """

  @auth_host "https://x.com"
  @api_host "https://api.x.com"

  def new_pkce_pair do
    verifier = :crypto.strong_rand_bytes(32) |> Base.url_encode64(padding: false)
    challenge = :crypto.hash(:sha256, verifier) |> Base.url_encode64(padding: false)
    {verifier, challenge}
  end

  def authorize_url(redirect_uri, state, code_challenge) do
    query =
      URI.encode_query(%{
        response_type: "code",
        client_id: client_id(),
        redirect_uri: redirect_uri,
        scope: "tweet.read tweet.write users.read offline.access",
        state: state,
        code_challenge: code_challenge,
        code_challenge_method: "S256"
      })

    "#{@auth_host}/i/oauth2/authorize?#{query}"
  end

  def exchange_code(code, redirect_uri, code_verifier) do
    post_token(%{
      grant_type: "authorization_code",
      code: code,
      redirect_uri: redirect_uri,
      code_verifier: code_verifier
    })
  end

  def refresh_token(refresh_token) do
    post_token(%{grant_type: "refresh_token", refresh_token: refresh_token})
  end

  defp post_token(params) do
    req()
    |> Req.post(
      url: "/2/oauth2/token",
      form: Map.put(params, :client_id, client_id()),
      auth: {:basic, "#{client_id()}:#{client_secret()}"}
    )
    |> handle_response()
  end

  def me(access_token) do
    req()
    |> Req.get(url: "/2/users/me", auth: {:bearer, access_token})
    |> handle_response()
  end

  def create_tweet(access_token, text) do
    req()
    |> Req.post(url: "/2/tweets", json: %{text: text}, auth: {:bearer, access_token})
    |> handle_response()
  end

  def user_tweets(access_token, user_id, opts \\ []) do
    max_results = Keyword.get(opts, :max_results, 5)

    req()
    |> Req.get(
      url: "/2/users/#{user_id}/tweets",
      params: [max_results: max_results, "tweet.fields": "created_at"],
      auth: {:bearer, access_token}
    )
    |> handle_response()
  end

  defp handle_response({:ok, %{status: status, body: body}}) when status in 200..299,
    do: {:ok, body}

  defp handle_response({:ok, %{status: status, body: body}}), do: {:error, {status, body}}
  defp handle_response({:error, reason}), do: {:error, reason}

  defp req, do: Req.new(base_url: @api_host)

  defp client_id, do: Application.fetch_env!(:app, :x_client_id)
  defp client_secret, do: Application.fetch_env!(:app, :x_client_secret)
end

Req handles JSON encoding/decoding on its own, so body above is already a decoded map — no separate Jason.decode!/1 step like you’d have needed with HTTPoison.

defmodule AppWeb.Plugs.AssignCurrentUser do
  import Plug.Conn

  def init(opts), do: opts

  def call(conn, _opts) do
    assign(conn, :current_user, get_session(conn, :current_user))
  end
end

Used only in TweetController, same as the original — no point gating the whole app behind auth for a demo.

defmodule AppWeb.Plugs.RequireUser do
  import Plug.Conn

  def init(opts), do: opts

  def call(conn, _opts) do
    if conn.assigns.current_user do
      conn
    else
      conn
      |> send_resp(401, "")
      |> halt()
    end
  end
end

defmodule AppWeb.Router do
  use AppWeb, :router

  pipeline :browser do
    plug :accepts, ["html"]
    plug :fetch_session
    plug :fetch_flash
    plug :protect_from_forgery
    plug :put_secure_browser_headers
    plug AppWeb.Plugs.AssignCurrentUser
  end

  scope "/", AppWeb do
    pipe_through :browser

    get "/", PageController, :index
    get "/auth/request", AuthController, :request
    get "/auth/callback", AuthController, :callback
    get "/auth/logout", AuthController, :logout

    resources "/tweets", TweetController, only: [:create]
  end
end

mix phx.routes still works the same way to double check what got wired up.

request/2 builds a PKCE pair, stashes the verifier and a random state value in the session, and sends the user to X’s authorize screen. callback/2 checks state matches (this is what stops a forged callback from hijacking a session), swaps the code for tokens, and fetches the user’s profile to store in the session.

defmodule AppWeb.AuthController do
  use AppWeb, :controller

  def request(conn, _params) do
    {verifier, challenge} = App.X.new_pkce_pair()
    state = Base.url_encode64(:crypto.strong_rand_bytes(16), padding: false)
    authorize_url = App.X.authorize_url(url(~p"/auth/callback"), state, challenge)

    conn
    |> put_session(:code_verifier, verifier)
    |> put_session(:oauth_state, state)
    |> redirect(external: authorize_url)
  end

  def callback(conn, %{"state" => state, "code" => code}) do
    if state == get_session(conn, :oauth_state) do
      verifier = get_session(conn, :code_verifier)

      with {:ok, token} <- App.X.exchange_code(code, url(~p"/auth/callback"), verifier),
           {:ok, %{"data" => user}} <- App.X.me(token["access_token"]) do
        conn
        |> put_session(:current_user, %{
          id: user["id"],
          username: user["username"],
          name: user["name"]
        })
        |> put_session(:access_token, token["access_token"])
        |> put_session(:refresh_token, token["refresh_token"])
        |> redirect(to: ~p"/")
      else
        _ ->
          conn
          |> put_flash(:error, "Something went wrong authenticating with X.")
          |> redirect(to: ~p"/")
      end
    else
      conn
      |> put_flash(:error, "Invalid OAuth state, please try again.")
      |> redirect(to: ~p"/")
    end
  end

  def callback(conn, %{"error" => _}) do
    conn
    |> put_flash(:error, "You did not authorize the app.")
    |> redirect(to: ~p"/")
  end

  def logout(conn, _params) do
    conn
    |> configure_session(drop: true)
    |> redirect(to: ~p"/")
  end
end

The two callback/2 clauses are the same pattern-matching trick from the original tutorial — one for a successful grant, one for when the user declines. It’s still one of my favorite things about Elixir.

defmodule AppWeb.PageController do
  use AppWeb, :controller

  def index(conn, _params) do
    case conn.assigns.current_user do
      nil ->
        render(conn, :logged_out)

      user ->
        access_token = get_session(conn, :access_token)
        {:ok, %{"data" => tweets}} = App.X.user_tweets(access_token, user.id, max_results: 5)
        render(conn, :logged_in, tweets: tweets)
    end
  end
end

Remember: reading user_tweets/3 back successfully depends on your project’s access tier. If you’re on the free tier, expect this call to fail — that’s X, not a bug in the code above. Pattern-match on {:error, _} here too if you want the page to degrade gracefully instead of crashing.

defmodule AppWeb.TweetController do
  use AppWeb, :controller

  plug AppWeb.Plugs.RequireUser

  def create(conn, %{"message" => message}) do
    access_token = get_session(conn, :access_token)

    case App.X.create_tweet(access_token, message) do
      {:ok, %{"data" => %{"id" => id}}} ->
        user = conn.assigns.current_user
        url = "https://x.com/#{user.username}/status/#{id}"

        conn
        |> put_flash(:info, "Posted! See #{url}")
        |> redirect(to: ~p"/")

      {:error, _reason} ->
        conn
        |> put_flash(:error, "Something went wrong posting that.")
        |> redirect(to: ~p"/")
    end
  end
end

defmodule AppWeb.PageHTML do
  use AppWeb, :html

  embed_templates "page_html/*"
end

lib/app_web/controllers/page_html/logged_out.html.heex:

<p>
  You are not signed in.
  <.link href={~p"/auth/request"} class="btn">Sign in with X</.link>
</p>

lib/app_web/controllers/page_html/logged_in.html.heex:

<h2>
  Welcome, <strong>{@current_user.name}</strong>!
  <.link href={~p"/auth/logout"} class="btn">Log out</.link>
</h2>

<form method="post" action={~p"/tweets"}>
  <input type="hidden" name="_csrf_token" value={Phoenix.Controller.get_csrf_token()} />
  <input type="text" name="message" placeholder="Post something..." maxlength="280" />
  <button type="submit">Post</button>
</form>

<h3>@{@current_user.username}'s recent posts</h3>

<div class="tweets">
  <%= for tweet <- @tweets do %>
    <div class="tweet-card">{tweet["text"]}</div>
  <% end %>
</div>

Note the {...} interpolation instead of <%= %> for simple values — that’s a HEEx-specific shorthand added in Phoenix 1.7 that only works inside tags and attributes; loops and other control flow still use <%= %> / <% %>.