Build status badge

Elixir package for authentication handling using Plug and Guardian (JWT). It supports X-API-KEY token and Authorization tokens, for external users or internal API communication.


API documentation at HexDocs


If available in Hex, the package can be installed by adding btrz_auth to your list of dependencies in mix.exs:

def deps do
  [{:btrz_ex_auth_api, "~> 0.7.0"}]

Add your configuration

config :btrz_ex_auth_api, :token,
    issuer: "your-issuer",
    main_secret: "YOUR_MAIN_KEY",
    secondary_secret: "YOUR_SECONDARY_KEY"


You can use the Guardian Plugs and the ones added by BtrzAuth:


Looks for the header or querystring x-api-key and verify the account, saving it into conn.private[:account].


It depends on BtrzAuth.Plug.VerifyApiKey, looks for a token in the Authorization header and verify it using first the account's private key loading the user id in the conn.private[:user_id], if not valid, then main and secondary secrets provided by your app for internal token cases.


Looks for and validates that the passed keys features are present in the account data under conn.private.account["premium"] saved by BtrzAuth.Plug.VerifyApiKey (the order of the plugs is very important!)



This pipeline will check the x-api-key header or querystring is sent and load the implemented resource in conn.private[:account].

  • plug BtrzAuth.Plug.VerifyApiKey


This pipeline will check the x-api-key header loading the account data in conn.private[:account] and also the token with the private key or the configured main and secondary secret keys in case the token could be an internal one, then ensure authenticated and load the implemented resource id in the conn.private[:user_id].

  • plug BtrzAuth.Plug.VerifyApiKey
  • plug BtrzAuth.Plug.VerifyToken
  • plug Guardian.Plug.EnsureAuthenticated

You can add pipelines in your Phoenix Router to get different authentication working.

pipeline :token_secured do
  plug BtrzAuth.Pipelines.TokenSecured

scope "/" do
  pipe_through :token_secured
  # your routes here...

Phoenix Channels

For Phoenix socket auth we wrap the Guardian.Phoenix.Socket module in order to use our internal-token, you might add to your user_socket.ex:

def connect(%{"token" => token}, socket) do
  case BtrzAuth.Phoenix.SocketAuth.authenticate(socket, token) do
    {:ok, authed_socket} ->
      {:ok, authed_socket}
    {:error, _} -> :error

def connect(_params, _socket) do

Integration tests in your API

Add the test_resource in order to test your endpoints once the plugs or pipelines are defined:

config :btrz_ex_auth_api, :token,
    issuer: "your-issuer",
    main_secret: "YOUR_MAIN_KEY",
    secondary_secret: "YOUR_SECONDARY_KEY"
    test_resource: %{account_id: "DESIRED_ID"}

and use "test-token" as your test token in the Authorization header.

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at