Release v0.12.0: Gemini authentication precedence and Live session API key support

- Update default Gemini auth resolution to prioritize application configuration
  (config :gemini_ex, api_key: ...) over the GEMINI_API_KEY environment variable.
- Modify Gemini.Client.HTTP to implicitly select Gemini auth when an api_key is
  passed, even if the :auth option is omitted.
- Enable Live session API key propagation by updating Gemini.Live.Session to
  pass per-session credentials through to WebSocket connections.
- Ensure WebSocket auth resolution favors connection-scoped keys before falling
  back to global configuration.
- Enhance documentation for the updated precedence order and session-scoped
  override paths.
- Add regression tests for config precedence, implicit HTTP auth selection,
  and proper propagation of Live session API keys.

Author: nshkrdotcom

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-04-02
+
+### Changed
+- **Gemini API key precedence**: default Gemini auth now prefers application configuration over `GEMINI_API_KEY`, making `config :gemini_ex, api_key: ...` the explicit default when both are present
+- **Published auth docs**: README, the Live API guide, and the authentication guide now document the new precedence order and the session-scoped Live override path
+
+### Fixed
+- **Implicit Gemini override selection**: `Gemini.Client.HTTP` now treats a request-scoped `api_key:` as sufficient to select Gemini auth even when `auth:` is omitted
+- **Live session API key overrides**: `Gemini.Live.Session.start_link/1` now propagates `api_key:` through to `Gemini.Client.WebSocket`, so per-session Gemini credentials do not depend on global config
+- **WebSocket auth resolution**: Gemini Live connections now prefer a connection-scoped API key before falling back to global configuration, with redacted logging preserved
+
+### Tests
+- Added focused regression coverage for config precedence, implicit HTTP auth selection, and Live session/WebSocket API key propagation
+
 ## [0.11.1] - 2026-03-27
 
 ### Added
@@ -1671,8 +1685,6 @@ similarity = ContentEmbedding.cosine_similarity(normalized, other_normalized)
 - Added `convert_thinking_config_to_api/1` to properly convert field names to camelCase
 - `GenerationConfig.ThinkingConfig` is now a typed struct (not plain map)
 
-## [Unreleased]
-
 ## [0.2.1] - 2025-08-08
 
 ### Added
@@ -2056,7 +2068,8 @@ config :gemini_ex,
 - Minimal latency overhead
 - Concurrent request processing
 
-[Unreleased]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.11.1...HEAD
+[Unreleased]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.11.1...v0.12.0
 [0.11.1]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.9.1...v0.10.0

README.md

@@ -59,7 +59,7 @@ Add `gemini` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:gemini_ex, "~> 0.11.1"}
+    {:gemini_ex, "~> 0.12.0"}
   ]
 end
 ```
@@ -83,6 +83,8 @@ Or set the environment variable:
 export GEMINI_API_KEY="your_api_key_here"
 ```
 
+For default Gemini auth resolution, `config :gemini_ex, api_key: ...` now takes precedence over `GEMINI_API_KEY`. Narrower overrides still win: pass `api_key:` directly on a request or on `Gemini.Live.Session.start_link/1` for session-scoped credentials.
+
 ### Simple Content Generation
 
 ```elixir
@@ -1377,15 +1379,25 @@ The examples follow a consistent pattern:
 
 ### Gemini API Key (Recommended for Development)
 
-```elixir
-# Environment variable (recommended)
+Default Gemini key precedence is:
+- Per-request or per-session `api_key:`
+- Application config: `config :gemini_ex, api_key: ...`
+- Environment variable: `GEMINI_API_KEY`
+
+```bash
 export GEMINI_API_KEY="your_api_key"
+```
 
-# Application config
+```elixir
 config :gemini_ex, api_key: "your_api_key"
 
-# Per-request override
 Gemini.generate("Hello", api_key: "specific_key")
+
+{:ok, session} =
+  Gemini.Live.Session.start_link(
+    model: Gemini.Live.Models.resolve(:text),
+    api_key: "session_specific_key"
+  )
 ```
 
 ### Vertex AI (Recommended for Production)

guides/AUTHENTICATION_SYSTEM.md

@@ -103,18 +103,16 @@ graph TD
 
 *   **Purpose**: To detect and load the *default* authentication credentials for the application.
 *   **Mechanism**: The `Gemini.Config.auth_config/0` function establishes a strict priority order for finding credentials:
-    1.  **Environment Variables**: Checks for `GEMINI_API_KEY`, `VERTEX_SERVICE_ACCOUNT`/`VERTEX_JSON_FILE`, and ADC vars such as `GOOGLE_APPLICATION_CREDENTIALS_JSON` and `GOOGLE_APPLICATION_CREDENTIALS`. This is the highest priority.
-    2.  **Application Config**: If no environment variables are found, it checks for `:gemini, :auth` or `:gemini, :api_key` in the Elixir application environment (e.g., `config/runtime.exs`).
+    1.  **Application Config**: Checks `:gemini, :auth`, `:gemini_ex, :auth`, and Gemini API keys configured via `:gemini` or `:gemini_ex`.
+    2.  **Environment Variables**: Falls back to `GEMINI_API_KEY`, `VERTEX_SERVICE_ACCOUNT`/`VERTEX_JSON_FILE`, and ADC vars such as `GOOGLE_APPLICATION_CREDENTIALS_JSON` and `GOOGLE_APPLICATION_CREDENTIALS`.
+    3.  **Per-request / per-session overrides**: Higher layers can still override the resolved defaults by passing `:api_key`, `:project_id`, or other auth opts directly on a request or Live session.
 *   **Code Example (`gemini/config.ex`):**
     ```elixir
     def auth_config do
-      cond do
-        gemini_api_key() ->
-          %{type: :gemini, credentials: %{api_key: gemini_api_key()}}
-        # ... other checks for Vertex, etc.
-        true ->
-          Application.get_env(:gemini, :auth) # ...
-      end
+      auth_config_from_app() ||
+        gemini_auth_config_from_env() ||
+        vertex_access_token_config_from_env() ||
+        vertex_service_account_config_from_env()
     end
     ```
 
@@ -239,6 +237,8 @@ The library will automatically detect and use these variables.
 
 Configure the library in your project's `config/runtime.exs` file. This is the canonical approach for managing secrets within an Elixir application.
 
+When both are present for Gemini auth, application config now takes precedence over `GEMINI_API_KEY`.
+
 *   **For Gemini API Key:**
     ```elixir
     # config/runtime.exs
@@ -275,15 +275,25 @@ When using `Gemini.Live.Session`, authentication is handled automatically using
 ```elixir
 alias Gemini.Live.{Models, Session}
 
-# Uses environment variable or application config
+# Uses application config or environment variables
 {:ok, session} = Session.start_link(
   model: Models.resolve(:text),
   auth: :gemini,  # or :vertex_ai
   generation_config: %{response_modalities: ["TEXT"]}
 )
 ```
 
-The WebSocket connection URL includes the API key as a query parameter (which is automatically redacted in logs for security).
+You can also scope a Gemini API key to a single Live session:
+
+```elixir
+{:ok, session} = Gemini.Live.Session.start_link(
+  model: Gemini.Live.Models.resolve(:text),
+  api_key: "session-specific-key",
+  generation_config: %{response_modalities: ["TEXT"]}
+)
+```
+
+The WebSocket connection URL includes the API key as a query parameter when Gemini auth is used, and that query parameter is automatically redacted in logs for security.
 
 #### Client-Side Authentication with Ephemeral Tokens
 

guides/live_api.md

@@ -286,6 +286,16 @@ model = Models.resolve(:text)
 # Session is now ready for messages
 ```
 
+For Gemini sessions, you can also pass `api_key:` directly to `Session.start_link/1`. When `api_key:` is present and `auth:` is omitted, the session uses Gemini auth for that connection only.
+
+```elixir
+{:ok, session} = Gemini.Live.Session.start_link(
+  model: Gemini.Live.Models.resolve(:text),
+  api_key: "session-specific-key",
+  generation_config: %{response_modalities: ["TEXT"]}
+)
+```
+
 ### Full Configuration Options
 
 ```elixir
@@ -297,6 +307,7 @@ alias Gemini.Live.Models
 
   # Authentication
   auth: :gemini,  # or :vertex_ai
+  api_key: "session-specific-key",  # optional per-session Gemini override when using Gemini auth
   project_id: "your-project",  # required for :vertex_ai
   location: "us-central1",     # optional, default: "us-central1"
   api_version: "v1alpha",

lib/gemini/client/http.ex

@@ -24,6 +24,16 @@ defmodule Gemini.Client.HTTP do
   alias Gemini.RateLimiter
   alias Gemini.Telemetry
 
+  @vertex_auth_override_keys [
+    :project_id,
+    :location,
+    :access_token,
+    :service_account_key,
+    :service_account,
+    :service_account_data,
+    :quota_project_id
+  ]
+
   @doc """
   Make a GET request using the configured authentication.
   """
@@ -142,7 +152,7 @@ defmodule Gemini.Client.HTTP do
 
   @spec resolve_auth_config(keyword()) :: Config.auth_config() | nil
   defp resolve_auth_config(opts) when is_list(opts) do
-    case normalize_auth_strategy(Keyword.get(opts, :auth)) do
+    case normalize_auth_strategy(Keyword.get(opts, :auth)) || infer_auth_strategy(opts) do
       nil ->
         Config.auth_config()
 
@@ -160,6 +170,14 @@ defmodule Gemini.Client.HTTP do
   defp normalize_auth_strategy(:vertex_ai), do: :vertex_ai
   defp normalize_auth_strategy(_), do: nil
 
+  defp infer_auth_strategy(opts) do
+    cond do
+      Keyword.has_key?(opts, :api_key) -> :gemini
+      Enum.any?(@vertex_auth_override_keys, &Keyword.has_key?(opts, &1)) -> :vertex_ai
+      true -> nil
+    end
+  end
+
   defp apply_auth_overrides(credentials, :gemini, opts) do
     credentials
     |> maybe_put_cred(:api_key, Keyword.get(opts, :api_key))

lib/gemini/client/websocket.ex

@@ -70,6 +70,7 @@ defmodule Gemini.Client.WebSocket do
           auth_strategy: auth_strategy() | nil,
           status: connection_status(),
           model: String.t() | nil,
+          api_key: String.t() | nil,
           project_id: String.t() | nil,
           location: String.t() | nil,
           api_version: String.t(),
@@ -98,6 +99,7 @@ defmodule Gemini.Client.WebSocket do
     :stream_ref,
     :auth_strategy,
     :model,
+    :api_key,
     :project_id,
     :location,
     status: :connecting,
@@ -187,6 +189,7 @@ defmodule Gemini.Client.WebSocket do
   def connect(auth_strategy, opts \\ []) do
     start_time = System.monotonic_time()
     model = Keyword.fetch!(opts, :model)
+    api_key = Keyword.get(opts, :api_key)
     project_id = Keyword.get(opts, :project_id)
     location = Keyword.get(opts, :location, "us-central1")
     api_version = Keyword.get(opts, :api_version, "v1beta")
@@ -201,6 +204,7 @@ defmodule Gemini.Client.WebSocket do
     conn = %__MODULE__{
       auth_strategy: auth_strategy,
       model: model,
+      api_key: api_key,
       project_id: project_id,
       location: location,
       api_version: api_version,
@@ -592,6 +596,11 @@ defmodule Gemini.Client.WebSocket do
   end
 
   @spec get_auth_params(t()) :: {:ok, map()} | {:error, term()}
+  defp get_auth_params(%__MODULE__{auth_strategy: :gemini, api_key: api_key})
+       when is_binary(api_key) and api_key != "" do
+    {:ok, %{api_key: api_key}}
+  end
+
   defp get_auth_params(%__MODULE__{auth_strategy: :gemini}) do
     case Config.api_key() do
       nil -> {:error, :no_api_key}

lib/gemini/config.ex

@@ -229,7 +229,7 @@ defmodule Gemini.Config do
       :gemini ->
         %{
           auth_type: :gemini,
-          api_key: gemini_api_key() || Application.get_env(:gemini_ex, :api_key),
+          api_key: api_key(),
           model: default_model()
         }
 
@@ -254,11 +254,11 @@ defmodule Gemini.Config do
   end
 
   @doc """
-  Detect authentication type based on environment variables.
+  Detect authentication type based on configured Gemini or Vertex credentials.
   """
   def detect_auth_type do
     cond do
-      gemini_api_key() -> :gemini
+      api_key() -> :gemini
       vertex_project_id() && vertex_project_id() != "" -> :vertex
       # default
       true -> :gemini
@@ -291,24 +291,23 @@ defmodule Gemini.Config do
 
   Returns a map with the authentication type and credentials.
   Priority order:
-  1. Environment variables
-  2. Application configuration
-  3. Default to Gemini with API key
+  1. Application configuration
+  2. Environment variables
   """
   @spec auth_config() :: auth_config() | nil
   def auth_config do
-    gemini_auth_config_from_env() ||
+    auth_config_from_app() ||
+      gemini_auth_config_from_env() ||
       vertex_access_token_config_from_env() ||
-      vertex_service_account_config_from_env() ||
-      auth_config_from_app()
+      vertex_service_account_config_from_env()
   end
 
   @doc """
-  Get the API key from environment or application config.
+  Get the API key from application config or environment.
   (Legacy function for backward compatibility)
   """
   def api_key do
-    gemini_api_key() || Application.get_env(:gemini_ex, :api_key)
+    Application.get_env(:gemini_ex, :api_key) || gemini_api_key()
   end
 
   defp gemini_auth_config_from_env do

lib/gemini/live/session.ex

@@ -298,14 +298,15 @@ defmodule Gemini.Live.Session do
   @impl true
   def init(opts) do
     model = Keyword.fetch!(opts, :model)
-    auth = Keyword.get(opts, :auth, detect_auth_strategy())
+    auth = Keyword.get(opts, :auth, detect_auth_strategy(opts))
 
     state = %{
       websocket: nil,
       status: :disconnected,
       config: %{
         model: model,
         auth: auth,
+        api_key: Keyword.get(opts, :api_key),
         project_id: Keyword.get(opts, :project_id),
         location: Keyword.get(opts, :location, "us-central1"),
         generation_config: Keyword.get(opts, :generation_config),
@@ -476,6 +477,7 @@ defmodule Gemini.Live.Session do
   defp do_connect(state) do
     base_opts = [
       model: state.config.model,
+      api_key: state.config.api_key,
       project_id: state.config.project_id,
       location: state.config.location
     ]
@@ -941,9 +943,10 @@ defmodule Gemini.Live.Session do
   @spec default_callback(term()) :: :ok
   defp default_callback(_), do: :ok
 
-  @spec detect_auth_strategy() :: :gemini | :vertex_ai
-  defp detect_auth_strategy do
+  @spec detect_auth_strategy(keyword()) :: :gemini | :vertex_ai
+  defp detect_auth_strategy(opts) do
     cond do
+      Keyword.get(opts, :api_key) -> :gemini
       Config.api_key() -> :gemini
       Config.get_auth_config(:vertex_ai)[:project_id] -> :vertex_ai
       true -> :gemini

mix.exs

@@ -1,7 +1,7 @@
 defmodule Gemini.MixProject do
   use Mix.Project
 
-  @version "0.11.1"
+  @version "0.12.0"
   @source_url "https://github.com/nshkrdotcom/gemini_ex"
 
   def project do