Connect LLM providers

ModuleX runs every language-model call through an LLM provider: a connector that exposes a set of models and one or more auth schemas. You connect a provider once, then any surface that calls a model — the Chat model selector, the Assistant, the LLM node, the Agent node, and the AI Composer — can use its models. There are two ways to connect a provider, and the difference is who pays and how:

ModuleX-managed (modulexai)

ModuleX provisions the upstream provider keys for you. Usage is metered in credits against your plan allowance and wallet. No provider account or key required.

Bring your own key (BYOK)

You supply your own provider API key. Usage is billed directly by the provider with no ModuleX markup, and is not charged in ModuleX credits (analytics-only).

🎬 MEDIA PLACEHOLDER · MX-MEDIA-4050 · [IMAGE] [IMAGE_DESCRIPTION]: Diagram of the two connection paths for an LLM provider. [IMAGE_DETAILS]: Show a single “LLM provider” box fanning into two lanes — “ModuleX-managed (modulexai, modulex_key auth)” routed through ModuleX-provisioned keys and metered in credits, and “BYOK (api_key auth)” routed directly to the upstream vendor and billed by the vendor. Label which lane consumes credits. 16:9, light and dark variants, ModuleX brand palette, no UI chrome.

Supported providers

The catalog ships these LLM providers. The wire name is the value you send as integration_name when you create a credential or pick a model.

Provider	Wire name	Connect with	Billing	Page
ModuleX-managed	`modulexai`	`modulex_key` (no key needed)	Credits	ModuleX-managed models
OpenAI	`openai`	`api_key` (BYOK)	Provider-direct	OpenAI
Anthropic	`anthropic`	`api_key` (BYOK)	Provider-direct	Anthropic
Google Gemini	`gemini`	`api_key` (BYOK)	Provider-direct	Google Gemini
xAI Grok	`xai`	`api_key` (BYOK)	Provider-direct	xAI Grok

Two further providers exist on the wire but are routing layers, not separately documented destinations. openrouter is a BYOK aggregator used internally to route many of the managed models, and bedrock carries only deprecated model ids that route to their replacements. Connect modulexai for managed access or a first-party provider above for BYOK; you do not need to connect openrouter or bedrock directly. See Selecting a model for how deprecated ids are handled, and the open questions below.

Each provider’s detail record is read-only metadata served by the catalog API (GET /integrations/llm-providers/{provider_name}). It carries the provider’s models[] and its auth_schemas[]; it never returns or stores your secret key.

Managed vs BYOK

The two modes differ in authentication, billing, and what you have to supply.

ModuleX-managed (modulexai)
Bring your own key (BYOK)

Wire name: modulexai.
Auth schema: modulex_key. ModuleX provides the upstream key automatically — setup_environment_variables is empty, so there is nothing for you to enter.
Billing: credited. Every managed turn is metered (see Credit cost) and flows through the billing admission gate, which can return a DenialEnvelope on 402 / 403 / 429 when your allowance and wallet are exhausted.
Use it when you want one provider with no key management, curated models, and unified usage tracking. It is the default and recommended provider.
Models are curated and may be routed across upstreams (for example, several modulexai models route through OpenRouter with a Bedrock-then-Anthropic fallback order). You select by ModuleX model_id; the routing is handled for you.

Wire names: openai, anthropic, gemini, xai.
Auth schema: api_key. You supply the provider’s key (and optionally a custom base_url for compatible endpoints).
Billing: uncosted in ModuleX credits. The upstream provider bills your account directly, with no ModuleX markup. ModuleX records BYOK calls for analytics only; the credit gate does not charge them.
Use it when you have provider accounts, want vendor-direct pricing, or need a specific model not offered under modulexai.
There is no feature.byok plan entitlement — BYOK is not plan-gated. You still need the owner or admin role to manage the provider credential.

Managed (modulexai) usage consumes credits and is subject to the billing gate; BYOK usage is not credited. Switching a chat, Assistant, or node from a modulexai model to a BYOK model moves that cost off your ModuleX credits and onto your provider bill, and vice versa. Confirm which model is selected before you rely on either billing path.

Connecting a provider

Managed access needs no setup — modulexai is available out of the box and requires no credential. For BYOK, you create a credential that stores your provider key (encrypted at rest), in the app or over the API.

In the app

Open the integration's connect screen

Open the integration catalog, find the provider (for example, OpenAI), and choose to connect it. You must be an owner or admin of the organization.

Enter your provider key

Paste the provider API key into the field defined by the provider’s api_key auth schema. Some providers also accept an optional Base URL for compatible endpoints.

Validate and save

ModuleX validates the key against the provider’s test_endpoint before saving (a minimal, low-cost request). On success the credential is stored and becomes selectable wherever models are chosen.

🎬 MEDIA PLACEHOLDER · MX-MEDIA-4051 · [SCREENSHOT] [SCREENSHOT_DESCRIPTION]: The connect-credential dialog for a BYOK LLM provider. [SCREENSHOT_DETAILS]: Capture the OpenAI provider connect modal showing the API Key field (masked), the optional Base URL field, and the validate/save action. Use a placeholder key value, never a real secret. Light theme, cropped to the dialog.

Over the API

Create the credential with POST /credentials. The request body is read raw and the auth type is auto-detected from the body — sending auth_data.api_key creates an api_key credential. Authenticate every request per Authentication: Authorization: Bearer mx_live_… plus X-Organization-ID.

integration_name

string

required

The provider wire name — openai, anthropic, gemini, or xai. Use modulexai only for managed access, which needs no key.

auth_data

object

required

The secret payload. For a BYOK provider, include api_key. The presence of auth_data.api_key is what selects the api_key credential type.

Show auth_data fields

auth_data.api_key

string

required

Your provider API key (for example, a key starting sk-ant- for Anthropic or sk- for OpenAI). Stored encrypted; never returned in responses.

auth_data.base_url

string

Optional custom base URL for a provider-compatible endpoint. Defaults to the provider’s standard API host when omitted.

display_name

string

A human-readable label for the credential, shown in the app and credential list.

make_default

boolean

default:"false"

When true, this credential becomes the default for the integration; any prior default for the same integration is unset.

curl -X POST https://api.modulex.dev/credentials \
  -H "Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organization-ID: 8f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_name": "openai",
    "display_name": "Production OpenAI key",
    "make_default": true,
    "auth_data": { "api_key": "sk-proj-xxxxxxxxxxxxxxxxxxxx" }
  }'

The SDK method names and shapes above follow the documented credential surface. Confirm the exact SDK method path against the SDK ⇄ API parity matrix; where an SDK lacks a method, call POST /credentials directly with cURL.

A successful create returns 201 with the credential record. To check a key before saving it, use POST /credentials/test-temporary with integration_name, auth_type: "api_key", and auth_data; it runs the provider’s validation endpoint and returns is_valid. For rotation, scoping, and listing, see Managing credentials.

Errors

Status	Shape	When
`400`	`{detail}`	`auth_data`/`auth_type` could not be resolved to a known credential type, or validation failed.
`401`	`{detail}`	Missing or invalid `Authorization`, or missing `X-Organization-ID`.
`403`	`{detail}`	You are not an owner or admin of the organization.
`500`	`{detail}`	Unexpected server error while creating the credential.

The credential routes return the FastAPI {detail} HTTPException envelope (a string message). The flat DenialEnvelope billing shape ({code, layer, key, current, limit, reason}) appears only on managed-usage surfaces — the run, Composer, Assistant, and managed-knowledge calls that actually meter credits — not on credential CRUD. See Errors & status codes for all three envelope shapes.

Selecting a model

A provider exposes its models in a models[] array. You select a model by its ModuleX model_id (for example, claude-sonnet-4.6), and ModuleX resolves that to the upstream wire model and request shape for you.

The model record

Each entry in models[] carries the fields below. Values come from the provider’s catalog record; pricing fields apply to BYOK provider-direct billing and inform managed credit metering.

string

The ModuleX model_id you select (for example, claude-opus-4.7, gpt-5.5, gemini-2.5-pro).

display_name

string

Human-readable model name shown in selectors.

provider

string

Display vendor, for example Anthropic or OpenAI.

provider_id

string

Routing provider slug — anthropic, openai, gemini, xai, or openrouter for models routed through the aggregator under modulexai.

max_input_tokens

integer

Maximum context window in tokens.

max_output_tokens

integer

Maximum tokens the model can generate. 0 for embedding models.

data_freshness

string

Knowledge-cutoff date (for example, 2026-01-01). This field, not a knowledge_cutoff key, carries the cutoff.

intelligence

integer

Quality score, 1–5.

speed

integer

Latency score, 1–5 (higher is faster).

supports_vision

boolean

Whether the model accepts image input.

input_usd_per_1m_tokens

number

Input price per 1M tokens, as a flat number (not a nested pricing object).

output_usd_per_1m_tokens

number

Output price per 1M tokens.

supports_tools

boolean

Present on some models — whether the model supports tool/function calling.

supports_structured_outputs

boolean

Present on some models — whether JSON-schema structured output is supported.

is_embedding

boolean

true for embedding models. Embedding models report embedding_dimension and a zero output price.

embedding_dimension

integer

Vector dimension for embedding models (for example, 3072 for text-embedding-3-large).

status

string

Lifecycle state. Present and set to deprecated on retired model ids.

replacement_id

string

On a deprecated model, the successor model_id that ModuleX routes the call to instead.

Show Example model record (Anthropic claude-opus-4.7)

{
  "id": "claude-opus-4.7",
  "display_name": "Claude Opus 4.7",
  "provider": "Anthropic",
  "provider_id": "anthropic",
  "max_input_tokens": 1000000,
  "max_output_tokens": 128000,
  "data_freshness": "2026-01-01",
  "intelligence": 5,
  "speed": 1,
  "supports_vision": true,
  "input_usd_per_1m_tokens": 5.0,
  "output_usd_per_1m_tokens": 25.0
}

Where you select a model

Chat — pick the model in the chat composer. See Model selection.
Assistant — set the model in Assistant settings. See Models & settings.
LLM node — set model_id on the node. See LLM node.
Agent node — set model_id on the node. See Agent node.

Deprecated models route automatically

When you select a model whose status is deprecated (or maintenance), ModuleX resolves it to its replacement_id before the call — for example, a bedrock-claude-sonnet-4.6 id routes to claude-sonnet-4.6. Routing is cycle- and depth-guarded, so a chain of replacements terminates at a live model. You do not need to update saved selections immediately, but prefer the live id for clarity.

Credit cost for managed usage

BYOK calls are not credited. Managed (modulexai) calls are metered two ways and charged against your credits:

Per-turn run charge — each logical run or chat turn is charged a flat RUN_CREDIT of 1 credit.
Token metering — the model’s tokens are converted to credits:

Token-to-credit formula

cost = (prompt_tokens · input_rate / 1e6 + completion_tokens · output_rate / 1e6) · MARGIN · SCALE

where input_rate/output_rate are the model’s input_usd_per_1m_tokens / output_usd_per_1m_tokens, MARGIN is 1.05 (a 5% system margin), and SCALE is 1000 (so **1000 credits =

1.00**, and 1 credit =

0.001). Embedding calls force completion_tokens = 0. An unknown model meters to 0, never a silent fallback rate. When managed usage exhausts your plan allowance and wallet, the call is denied with a DenialEnvelope on 402 / 403 / 429. See Credits & metering and Usage gating & limits for the full model.

Permissions and access

Connecting, listing, and managing LLM-provider credentials requires the owner or admin role in the organization (member is retired). Every request also needs the org context header X-Organization-ID; a missing header is rejected. See Roles & permissions and Org context & X-Organization-ID.

Per-provider pages

ModuleX-managed models

The default managed provider (modulexai), billed in credits — no key required.

OpenAI

Connect your OpenAI account (BYOK) and use GPT models.

Anthropic

Connect your Anthropic account (BYOK) and use Claude models.

Google Gemini

Connect your Google account (BYOK) and use Gemini models.

xAI Grok

Connect your xAI account (BYOK) and use Grok models.

Authentication & credentials — the auth-schema variants and OAuth2 flow for integrations.
Managing credentials — create, rotate, scope, and test credentials.
Knowledge providers — the vector-store side of managed vs BYOK.
Credits & metering — what consumes credits and how it is measured.

Open questions (TBD)

OpenRouter and Bedrock pages. Both names exist on the wire (openrouter as the BYOK aggregator behind several managed models; bedrock carrying only deprecated, replacement-routed ids), but neither has a canonical documentation page in the current information architecture. Whether to document them as standalone connectable providers is TBD pending a product decision.
Public catalog base URL. The provider catalog and credential examples use https://api.modulex.dev per the repo-wide convention; the exact public host for these endpoints is not pinned from source and should be confirmed against the deployed environment.

ModuleX-managed (modulexai)

Bring your own key (BYOK)

​Supported providers

​Managed vs BYOK

​Connecting a provider

​In the app

​Over the API

​Errors

​Selecting a model

​The model record

​Where you select a model

​Deprecated models route automatically

​Credit cost for managed usage

​Permissions and access

​Per-provider pages

ModuleX-managed models

OpenAI

Anthropic

Google Gemini

xAI Grok

​Related

​Open questions (TBD)

Supported providers

Managed vs BYOK

Connecting a provider

In the app

Over the API

Errors

Selecting a model

The model record

Where you select a model

Deprecated models route automatically

Credit cost for managed usage

Permissions and access

Per-provider pages

Related

Open questions (TBD)