PhoenixKit.API.Config (phoenix_kit v2.64.1)

Settings accessors for the machine API.

Every function reads a core setting through PhoenixKit.Settings and applies a safe default. The API is off by default and fails closed: a switch is on only when its setting reads exactly "true", so a missing row, an unreadable database, an unexpected value or a Settings error all count as off.

Settings

Key	Default
`api_admin_enabled`	`false`
`api_public_enabled`	`false`
`api_disabled_tools`	`""` (newline separated tool names)
`api_disabled_modules`	`""` (newline separated module keys)
`api_session_write_modules`	`""` (newline separated module keys)
`api_mcp_allowed_origins`	`""` (newline separated origins)
`api_admin_preauth_fail_per_min`	`20`
`api_admin_rate_per_min`	`600`
`api_public_token_rate_per_min`	`120`
`api_public_ip_rate_per_min`	`300`
`api_public_new_rows_per_ip_hour`	`120`
`api_public_new_rows_global_hour`	`2000`

The three api_public_token_* and api_public_new_rows_* limits were renamed when the API was made module-neutral. While the deprecation window lasts (PhoenixKit.API.Legacy) a limit whose new key holds no valid number reads its old key, then the default.

List settings are stored as newline-separated strings: PhoenixKit.Settings has no list setter and a JSON setting cannot hold a bare list. Use encode_list/1 when writing one and parse_list/1 when reading one.

Summary

Types

rate_limits()

Functions

admin_enabled?()

Whether the admin API (/api/admin/v1) is switched on. Fails closed.

disabled_modules()

Module keys whose API tools the install has switched off (api_disabled_modules). For display only, like disabled_tools/0: a list that cannot be read is [] here.

disabled_tools()

Tool names the install has hidden (api_disabled_tools). For display only: a list that cannot be read is [] here, so request paths (PhoenixKit.API.Registry) use fetch_disabled_tools/0, which does not treat it as "nothing is hidden".

encode_list(items)

Joins a list into the newline-separated form the list settings are stored in.

fetch_disabled_modules()

Module keys whose API tools the install has switched off (api_disabled_modules), telling an empty list from one that could not be read at all. A module that is not in the list has its API on, so every install starts with all of them on.

fetch_disabled_tools()

Tool names the install has hidden (api_disabled_tools), telling a list that is empty from one that could not be read at all (a read that raises or exits).

fetch_session_write_modules()

Module keys whose write tools a person's live session may call (api_session_write_modules), telling an empty list from one that could not be read.

int(key, default)

Reads an integer setting.

int(key, legacy_key, default)

Reads an integer setting that was renamed: the value of key when it is a valid limit (see int/2), else the value of legacy_key when that is, else default. A nil legacy_key reads key alone.

max_body_bytes()

Largest request body the API accepts, in bytes (2 MB).

mcp_allowed_origins()

Extra origins allowed to call the MCP endpoint (api_mcp_allowed_origins).

parse_list(value)

Splits a newline-separated setting value into a list.

public_enabled?()

Whether the public API (/api/public/v1, MCP) is switched on. Fails closed.

rate_limits()

The rate-limit settings as one map.

rate_limits_without_fallback()

The rate-limit settings as rate_limits/0 gives them, but reading each key alone: the deprecated key of a renamed limit is not consulted. The settings form compares what it is given with this, so that its first save writes a value that was in effect through a deprecated key under the new key. Goes away with PhoenixKit.API.Legacy.

session_write_modules()

Module keys whose write tools a person's live session may call (api_session_write_modules, the "Agent may act" boxes of Settings -> API). For display only, like disabled_modules/0: a list that cannot be read is [] here.

Types

rate_limits()

@type rate_limits() :: %{
  preauth_fail_per_min: pos_integer(),
  admin_per_min: pos_integer(),
  public_token_per_min: pos_integer(),
  public_ip_per_min: pos_integer(),
  new_rows_ip_hour: pos_integer(),
  new_rows_global_hour: pos_integer()
}

Functions

admin_enabled?()

@spec admin_enabled?() :: boolean()

Whether the admin API (/api/admin/v1) is switched on. Fails closed.

disabled_modules()

@spec disabled_modules() :: [String.t()]

Module keys whose API tools the install has switched off (api_disabled_modules). For display only, like disabled_tools/0: a list that cannot be read is [] here.

disabled_tools()

@spec disabled_tools() :: [String.t()]

encode_list(items)

@spec encode_list([String.t()]) :: String.t()

Joins a list into the newline-separated form the list settings are stored in.

fetch_disabled_modules()

@spec fetch_disabled_modules() :: {:ok, [String.t()]} | :unreadable

The tool registry fails closed on :unreadable, as with fetch_disabled_tools/0. This is the one reader of the setting.

fetch_disabled_tools()

@spec fetch_disabled_tools() :: {:ok, [String.t()]} | :unreadable

Tool names the install has hidden (api_disabled_tools), telling a list that is empty from one that could not be read at all (a read that raises or exits).

The tool registry fails closed on :unreadable: a tool the admin switched off must not come back because of a settings problem. This is the one reader of the setting.

fetch_session_write_modules()

@spec fetch_session_write_modules() :: {:ok, [String.t()]} | :unreadable

Module keys whose write tools a person's live session may call (api_session_write_modules), telling an empty list from one that could not be read.

An allow-list that fails closed: a module that is not listed has no write for a session, so every install starts with none, and the executor treats :unreadable as an empty list. API keys do not read it. This is the one reader of the setting.

int(key, default)

@spec int(String.t(), integer()) :: integer()

Reads an integer setting.

Returns default when the setting is missing, is not a whole number ("12abc" and "1.5" are not read by their prefix), is zero or negative, or cannot be read. Every API integer setting is a positive limit, and a zero limit would silently refuse every request, so a non-positive value is treated as unset.

int(key, legacy_key, default)

@spec int(String.t(), String.t() | nil, integer()) :: integer()

max_body_bytes()

@spec max_body_bytes() :: 2_097_152

Largest request body the API accepts, in bytes (2 MB).

mcp_allowed_origins()

@spec mcp_allowed_origins() :: [String.t()]

Extra origins allowed to call the MCP endpoint (api_mcp_allowed_origins).

parse_list(value)

@spec parse_list(String.t() | nil) :: [String.t()]

Splits a newline-separated setting value into a list.

Lines are trimmed; blank lines and duplicates are dropped. nil is [].

public_enabled?()

@spec public_enabled?() :: boolean()

Whether the public API (/api/public/v1, MCP) is switched on. Fails closed.

rate_limits()

@spec rate_limits() :: rate_limits()

The rate-limit settings as one map.

*_per_min limits count over a 60 second window and *_hour limits over a one hour window (see PhoenixKit.API.RateLimit).

rate_limits_without_fallback()

@spec rate_limits_without_fallback() :: rate_limits()

session_write_modules()

@spec session_write_modules() :: [String.t()]