PhoenixKit.Integrations.Providers (phoenix_kit v2.1.0)

Registry of known integration providers.

Each provider definition describes how to connect to an external service: what auth type it uses, what fields the admin needs to fill in, and how to validate the connection.

Providers are defined in code, not in the database. New providers are added here as needed. External modules can also contribute providers via the integration_providers/0 callback on PhoenixKit.Module.

Summary

Types

auth_type()

provider()

setup_field()

Functions

all()

Returns all known providers, including those contributed by external modules.

base_url(key)

Returns the API base URL declared by a provider, or nil if it has none.

clear_cache()

Clears the cached provider list and used-by map.

for_scope(scope)

All providers usable under scope (:system or :personal).

get(key)

Look up a single provider by key.

personal_offered()

Providers offered on the personal integrations "add" picker — the subset of for_scope(:personal) currently exposed (see @personal_offered), returned in that list's order.

scopes_of(provider)

The scopes a provider may hold a connection under. Defaults to [:system] when the provider omits :scopes (so an external module's provider never lands on the personal page unless it opts in).

used_by_modules()

Returns a map of provider_key => [module_name] showing which modules use each integration.

with_capability(capability)

Returns all providers (built-in + external) that declare the given capability.

Types

auth_type()

@type auth_type() :: :oauth2 | :api_key | :key_secret | :bot_token | :credentials

provider()

@type provider() :: %{
  :key => String.t(),
  :name => String.t(),
  :description => String.t(),
  :icon => String.t(),
  :auth_type => auth_type(),
  :oauth_config => map() | nil,
  :setup_fields => [setup_field()],
  :capabilities => [atom()],
  optional(:base_url) => String.t(),
  optional(:validation) => map(),
  optional(:instructions) => [map()],
  optional(:scopes) => [:system | :personal]
}

setup_field()

@type setup_field() :: %{
  key: String.t(),
  label: String.t(),
  type: :text | :password | :textarea | :number | :select,
  required: boolean(),
  placeholder: String.t(),
  help: String.t() | nil,
  options: [%{value: String.t(), label: String.t()}] | nil
}

Functions

all()

@spec all() :: [provider()]

Returns all known providers, including those contributed by external modules.

Results are cached in persistent_term after the first call. Call clear_cache/0 if modules are added or removed at runtime.

base_url(key)

@spec base_url(String.t()) :: String.t() | nil

Returns the API base URL declared by a provider, or nil if it has none.

Accepts the same plain or named keys as get/1 ("openai" / "openai:work"). Only providers with a primary REST API (currently the :ai_completions providers) declare a :base_url; everything else is nil.

clear_cache()

@spec clear_cache() :: :ok

Clears the cached provider list and used-by map.

Call this when modules are added or removed at runtime so the next call to all/0 or used_by_modules/0 recomputes from the module registry.

for_scope(scope)

@spec for_scope(:system | :personal) :: [provider()]

All providers usable under scope (:system or :personal).

Drives the provider grid on each page — the system setup lists for_scope(:system), the personal setup lists for_scope(:personal).

get(key)

@spec get(String.t()) :: provider() | nil

Look up a single provider by key.

Accepts both plain keys ("google") and named keys ("google:personal") — the name is stripped before lookup since provider definitions are per-type.

personal_offered()

@spec personal_offered() :: [provider()]

Providers offered on the personal integrations "add" picker — the subset of for_scope(:personal) currently exposed (see @personal_offered), returned in that list's order.

scopes_of(provider)

@spec scopes_of(String.t() | provider()) :: [:system | :personal]

The scopes a provider may hold a connection under. Defaults to [:system] when the provider omits :scopes (so an external module's provider never lands on the personal page unless it opts in).

used_by_modules()

@spec used_by_modules() :: %{required(String.t()) => [String.t()]}

Returns a map of provider_key => [module_name] showing which modules use each integration.

with_capability(capability)

@spec with_capability(atom()) :: [provider()]

Returns all providers (built-in + external) that declare the given capability.

Lets consumers discover providers by what they can do rather than by a hardcoded list. For example, an AI module can render its provider picker from with_capability(:ai_completions), so adding a new chat provider to the registry surfaces it automatically.

Order follows all/0 (built-ins first, in definition order).