Make API auth mandatory, manage tokens via web UI

BREAKING CHANGE: API authentication is now always required. The
PINCHFLAT_API_TOKEN env var is no longer used. Instead, tokens are
stored in the database and managed via Settings → API Access.

Changes:
- Add api_token column to settings table (migration)
- ApiAuthPlug reads from DB; returns 401 if no token configured
- Add API Access section to Settings page with generate/regenerate/revoke
- Add POST /settings/generate_api_token and /settings/revoke_api_token
- Remove api_token from config.exs and runtime.exs
- Update all API controller tests to set auth token in setup
- Update auth plug tests for mandatory authentication
- 1008 tests pass, zero warnings

config/config.exs

@@ -26,7 +26,6 @@ config :pinchflat,
   basic_auth_username: "",
   basic_auth_password: "",
   expose_feed_endpoints: false,
-  api_token: "",
   file_watcher_poll_interval: 1000,
   timezone: "UTC",
   base_route_path: "/"

config/runtime.exs

@@ -23,8 +23,7 @@ end
 
 config :pinchflat,
   basic_auth_username: System.get_env("BASIC_AUTH_USERNAME"),
-  basic_auth_password: System.get_env("BASIC_AUTH_PASSWORD"),
+  basic_auth_password: System.get_env("BASIC_AUTH_PASSWORD")
-  api_token: System.get_env("PINCHFLAT_API_TOKEN")
 
 arch_string = to_string(:erlang.system_info(:system_architecture))
 

config/test.exs

@@ -12,10 +12,6 @@ config :pinchflat,
 
 config :pinchflat, Oban, testing: :manual
 
-# API token is not set in tests by default — allows tests to run without auth.
-# Individual tests that need auth can set it via Application.put_env.
-config :pinchflat, :api_token, nil
-
 # Configure your database
 #
 # The MIX_TEST_PARTITION environment variable can be used

docs/API.md

@@ -5,22 +5,17 @@ MCP server integration and other automation use cases.
 
 ## API Authentication
 
-The API is protected by a Bearer token. Set the `PINCHFLAT_API_TOKEN`
+The API always requires a Bearer token — there is no open-access mode.
-environment variable to a secure value:
+Generate a token from the web UI under **Settings → API Access**:
 
-```bash
+1. Navigate to Settings
-docker run \
+2. Click "Generate API Token"
-  -e PINCHFLAT_API_TOKEN=your-secret-token \
+3. Copy the token (it won't be shown in full again)
-  ...
-```
-
-If the token is not set, API authentication is disabled (useful for
-development, but **not recommended for production**).
 
 Clients must send the token in the `Authorization` header:
 
 ```
-Authorization: Bearer your-secret-token
+Authorization: Bearer *** to regenerate or revoke the token at any time.
 ```
 
 ## API Endpoints

lib/pinchflat/settings/setting.ex

@@ -17,7 +17,8 @@ defmodule Pinchflat.Settings.Setting do
     :youtube_api_key,
     :extractor_sleep_interval_seconds,
     :download_throughput_limit,
-    :restrict_filenames
+    :restrict_filenames,
+    :api_token
   ]
 
   @required_fields [
@@ -40,6 +41,7 @@ defmodule Pinchflat.Settings.Setting do
     # This is a string because it accepts values like "100K" or "4.2M"
     field :download_throughput_limit, :string
     field :restrict_filenames, :boolean, default: false
+    field :api_token, :string
 
     field :video_codec_preference, :string
     field :audio_codec_preference, :string

lib/pinchflat_web/api_auth_plug.ex

@@ -2,21 +2,21 @@ defmodule PinchflatWeb.ApiAuthPlug do
   @moduledoc """
   Authenticates API requests using a Bearer token.
 
-  The token is read from the `PINCHFLAT_API_TOKEN` environment variable.
+  The token is stored in the settings database and managed via the web UI.
-  If the environment variable is not set, API authentication is disabled
+  A token must be generated before API access is possible — the API is
-  (useful for development and testing). In production, you should always
+  always authenticated, there is no open-access mode.
-  set this to a secure value.
 
   Clients should send the token in the Authorization header:
     Authorization: Bearer <token>
   """
 
   import Plug.Conn
+  alias Pinchflat.Settings
 
   def init(opts), do: opts
 
   def call(conn, _opts) do
-    expected_token = Application.get_env(:pinchflat, :api_token)
+    expected_token = Settings.get!(:api_token)
 
     if credential_set?(expected_token) do
       case get_req_header(conn, "authorization") do
@@ -31,8 +31,8 @@ defmodule PinchflatWeb.ApiAuthPlug do
           send_unauthorized(conn)
       end
     else
-      # No API token configured — allow access (dev/test mode)
+      # No API token has been generated yet — deny all access
-      conn
+      send_unauthorized(conn, "API token not configured. Generate one in Settings.")
     end
   end
 
@@ -40,10 +40,10 @@ defmodule PinchflatWeb.ApiAuthPlug do
     credential && credential != ""
   end
 
-  defp send_unauthorized(conn) do
+  defp send_unauthorized(conn, message \\ "Unauthorized") do
     conn
     |> put_resp_content_type("application/json")
-    |> send_resp(401, ~s({"errors":{"detail":"Unauthorized"}}))
+    |> send_resp(401, ~s({"errors":{"detail":"#{message}"}}))
     |> halt()
   end
 end

lib/pinchflat_web/controllers/settings/setting_controller.ex

@@ -28,6 +28,36 @@ defmodule PinchflatWeb.Settings.SettingController do
     render(conn, "app_info.html")
   end
 
+  def generate_api_token(conn, _params) do
+    token = :crypto.strong_rand_bytes(32) |> Base.url_encode64(padding: false)
+
+    case Settings.set(api_token: token) do
+      {:ok, _} ->
+        conn
+        |> put_flash(:info, "API token generated successfully.")
+        |> redirect(to: ~p"/settings")
+
+      {:error, _} ->
+        conn
+        |> put_flash(:error, "Failed to generate API token.")
+        |> redirect(to: ~p"/settings")
+    end
+  end
+
+  def revoke_api_token(conn, _params) do
+    case Settings.set(api_token: nil) do
+      {:ok, _} ->
+        conn
+        |> put_flash(:info, "API token revoked.")
+        |> redirect(to: ~p"/settings")
+
+      {:error, _} ->
+        conn
+        |> put_flash(:error, "Failed to revoke API token.")
+        |> redirect(to: ~p"/settings")
+    end
+  end
+
   def download_logs(conn, _params) do
     log_path = Application.get_env(:pinchflat, :log_path)
 

lib/pinchflat_web/controllers/settings/setting_html/setting_form.html.heex

@@ -26,6 +26,44 @@
     )}
   </section>
 
+  <section class="mt-8">
+    <h3 class="text-2xl text-black dark:text-white">
+      API Access
+    </h3>
+    <p class="text-sm mt-2 max-w-prose text-bodydark2">
+      Generate a token to authenticate requests to the <code class="font-mono">/api/v1</code> REST API.
+      Required for MCP server integration and other programmatic clients.
+      Send it as <code class="font-mono">Authorization: Bearer &lt;token&gt;</code>.
+    </p>
+
+    <div class="mt-4">
+      <%= if Settings.get!(:api_token) do %>
+        <div class="flex items-center gap-3 flex-wrap">
+          <code class="font-mono text-sm bg-meta-2 dark:bg-meta-4 px-3 py-2 rounded break-all">
+            {String.slice(Settings.get!(:api_token), 0, 12)}••••••••
+          </code>
+          <.link href={~p"/settings/generate_api_token"} method="post">
+            <.button rounding="rounded-lg" class="bg-warning hover:bg-warning/80">Regenerate Token</.button>
+          </.link>
+          <.link
+            href={~p"/settings/revoke_api_token"}
+            method="post"
+            data-confirm="Are you sure? This will immediately disable all API access."
+          >
+            <.button rounding="rounded-lg" class="bg-danger hover:bg-danger/80">Revoke Token</.button>
+          </.link>
+        </div>
+      <% else %>
+        <p class="text-sm text-danger mb-3">
+          No API token configured. The API is currently inaccessible.
+        </p>
+        <.link href={~p"/settings/generate_api_token"} method="post">
+          <.button rounding="rounded-lg" class="bg-primary hover:bg-primary/80">Generate API Token</.button>
+        </.link>
+      <% end %>
+    </div>
+  </section>
+
   <section class="mt-8">
     <section>
       <h3 class="text-2xl text-black dark:text-white">

lib/pinchflat_web/router.ex

@@ -52,6 +52,8 @@ defmodule PinchflatWeb.Router do
     resources "/search", Searches.SearchController, only: [:show], singleton: true
 
     resources "/settings", Settings.SettingController, only: [:show, :update], singleton: true
+    post "/settings/generate_api_token", Settings.SettingController, :generate_api_token
+    post "/settings/revoke_api_token", Settings.SettingController, :revoke_api_token
     get "/app_info", Settings.SettingController, :app_info
     get "/download_logs", Settings.SettingController, :download_logs
 

priv/repo/migrations/20260704114239_add_api_token_to_settings.exs

@@ -0,0 +1,9 @@
+defmodule Pinchflat.Repo.Migrations.AddApiTokenToSettings do
+  use Ecto.Migration
+
+  def change do
+    alter table(:settings) do
+      add :api_token, :string
+    end
+  end
+end

test/pinchflat_web/api_auth_plug_test.exs

@@ -2,24 +2,34 @@ defmodule PinchflatWeb.ApiAuthPlugTest do
   use PinchflatWeb.ConnCase
 
   import Pinchflat.ProfilesFixtures
+  alias Pinchflat.Settings
 
   setup do
-    # Ensure api_token is not set by default in tests
+    # Ensure api_token is cleared in DB for each test
-    Application.put_env(:pinchflat, :api_token, nil)
+    Settings.set(api_token: nil)
     :ok
   end
 
   describe "when no api_token is configured" do
-    test "allows access without Authorization header", %{conn: conn} do
+    test "returns 401 without Authorization header", %{conn: conn} do
       conn = get(conn, ~p"/api/v1/media_profiles")
-      assert %{status: 200} = conn
+
+      assert %{status: 401} = conn
+    end
+
+    test "returns 401 even with a Bearer token", %{conn: conn} do
+      conn =
+        conn
+        |> put_req_header("authorization", "Bearer some-token")
+        |> get(~p"/api/v1/media_profiles")
+
+      assert %{status: 401} = conn
     end
   end
 
   describe "when api_token is configured" do
     setup do
-      Application.put_env(:pinchflat, :api_token, "secret-token-123")
+      Settings.set(api_token: "secret-token-123")
-      on_exit(fn -> Application.put_env(:pinchflat, :api_token, nil) end)
       :ok
     end
 

test/pinchflat_web/controllers/api/v1/api_media_item_controller_test.exs

@@ -1,6 +1,16 @@
 defmodule PinchflatWeb.Api.V1.ApiMediaItemControllerTest do
   use PinchflatWeb.ConnCase
 
+  setup do
+    Pinchflat.Settings.set(api_token: "test-token")
+
+    conn =
+      build_conn()
+      |> put_req_header("authorization", "Bearer test-token")
+
+    {:ok, conn: conn}
+  end
+
   import Pinchflat.MediaFixtures
   import Pinchflat.SourcesFixtures
   import Pinchflat.ProfilesFixtures

test/pinchflat_web/controllers/api/v1/api_media_profile_controller_test.exs

@@ -1,6 +1,16 @@
 defmodule PinchflatWeb.Api.V1.ApiMediaProfileControllerTest do
   use PinchflatWeb.ConnCase
 
+  setup do
+    Pinchflat.Settings.set(api_token: "test-token")
+
+    conn =
+      build_conn()
+      |> put_req_header("authorization", "Bearer test-token")
+
+    {:ok, conn: conn}
+  end
+
   import Pinchflat.ProfilesFixtures
 
   describe "GET /api/v1/media_profiles" do

test/pinchflat_web/controllers/api/v1/api_setting_controller_test.exs

@@ -1,6 +1,16 @@
 defmodule PinchflatWeb.Api.V1.ApiSettingControllerTest do
   use PinchflatWeb.ConnCase
 
+  setup do
+    Pinchflat.Settings.set(api_token: "test-token")
+
+    conn =
+      build_conn()
+      |> put_req_header("authorization", "Bearer test-token")
+
+    {:ok, conn: conn}
+  end
+
   import Pinchflat.ProfilesFixtures
 
   alias Pinchflat.Settings

test/pinchflat_web/controllers/api/v1/api_source_controller_test.exs

@@ -1,6 +1,16 @@
 defmodule PinchflatWeb.Api.V1.ApiSourceControllerTest do
   use PinchflatWeb.ConnCase
 
+  setup do
+    Pinchflat.Settings.set(api_token: "test-token")
+
+    conn =
+      build_conn()
+      |> put_req_header("authorization", "Bearer test-token")
+
+    {:ok, conn: conn}
+  end
+
   import Pinchflat.MediaFixtures
   import Pinchflat.SourcesFixtures
   import Pinchflat.ProfilesFixtures

test/pinchflat_web/controllers/api/v1/api_task_controller_test.exs

@@ -1,6 +1,16 @@
 defmodule PinchflatWeb.Api.V1.ApiTaskControllerTest do
   use PinchflatWeb.ConnCase
 
+  setup do
+    Pinchflat.Settings.set(api_token: "test-token")
+
+    conn =
+      build_conn()
+      |> put_req_header("authorization", "Bearer test-token")
+
+    {:ok, conn: conn}
+  end
+
   import Pinchflat.SourcesFixtures
   import Pinchflat.MediaFixtures