Gateway

Appearance

Add providers & keys ​

There are two different kinds of credential in merido. Keeping them straight is the key to a correct setup.

Two kinds of credential ​

  1. Client / gateway keys — what callers use to authenticate to merido. Your coding CLIs put one of these in their Authorization: Bearer … header. They never leave your control. In the dashboard these are branded Gateway keys.
  2. Upstream provider credentials — what merido uses to call the providers on your behalf: either a provider API key or an OAuth connection (for subscription accounts). These are stored encrypted at rest.

A request flows: your tool → (gateway key) → merido → (provider credential) → the upstream model.

Client (gateway) keys ​

Create one from the CLI:

bash
merido keys create --name "my-laptop"
# optional expiry:
merido keys create --name "ci" --ttl-seconds 86400

The key is shown once — store it immediately. Or create and manage them in the dashboard under Gateway keys (rotate, rename, revoke).

On a multi-tenant (cloud) gateway, tick Personal key when creating a key in the dashboard to let it use your private ChatGPT accounts as well as your organization's shared providers. Only you can rotate a personal key; any key manager can still revoke it.

Upstream providers — API key ​

Add a provider connection with an API key:

bash
merido providers add --provider openai --api-key sk-...
  • --provider is the provider key, e.g. openai, anthropic, openrouter, deepseek.
  • --base-url is optional — it defaults to the provider's known endpoint from merido's registry.
  • --label is an optional human-readable name.

The upstream key is encrypted at rest with your master key (data_dir/master.key, or MERIDO_MASTER_KEY). You can also add connections from the dashboard Providers page, which unifies API-key and OAuth providers in one place.

TypeSafe (System One) ​

TypeSafe's Jev models answer structured decisions about a piece of content — choices, scores and yes/no probabilities — instead of generating text. Create a key in the TypeSafe console and add it as the typesafe provider (dashboard Providers page, or merido providers add --provider typesafe --api-key <key>). The base URL defaults to https://api.typesafe.ai/v1, and the models (jev-latest, jev-preview, …) are discovered from TypeSafe's own /v1/models.

Agents call it through merido's native POST /v1/systemone, which forwards TypeSafe's request (with model rewritten to the bare id) and its successful response unchanged:

bash
curl https://your-gateway.example/v1/systemone \
  -H "Authorization: Bearer <gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-latest",
    "state": "I was charged twice for my subscription. Please help.",
    "questions": {
      "billing": { "type": "noul", "instructions": "Is this message about billing?" },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this message?",
        "criteria": ["Can wait", "Needs attention this week", "Needs attention today"]
      }
    }
  }'
  • model is typesafe/<model>, TypeSafe's bare id (jev-latest), or the name of a TypeSafe Virtual Model — a VM name is what a gateway running MERIDO_VIRTUAL_MODELS_ONLY accepts, since a raw id is refused there.
  • A key's allowed_models is matched against the string as sent, so typesafe/* admits only the namespaced form and a VM name must be listed by name.
  • The gateway key's rate limits (RPM and TPM) and budgets apply. The org's TypeSafe connections are tried in priority order (a dead or throttled key falls over to the next), and each call is recorded in Usage at TypeSafe's input-token rate (output tokens are free).
  • TypeSafe validates state and questions itself; its errors (e.g. 422) keep their status and arrive in merido's standard error envelope.
  • System One is not chat and does not stream: typesafe/… models are refused on the chat endpoints (a Virtual Model target on one is skipped), and neither the built-in auto model nor Virtual Model auto-generation picks them.

Cloudflare AI Gateway / Workers AI ​

The cloudflare provider calls Cloudflare's unified REST API natively: Workers AI models and third-party models (billed through Cloudflare Unified Billing, or your provider keys stored in Cloudflare as BYOK) go through one AI Gateway, so its logs, analytics, caching, rate limits, spend limits and routing apply to Merido traffic.

On the dashboard Providers page, pick Cloudflare AI Gateway / Workers AI and enter:

  • a Cloudflare API token with Account › Workers AI › Read — required even for third-party models;
  • your 32-character account ID;
  • the AI Gateway ID (default unless you created another gateway).

Merido stores the endpoint as https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>; from the CLI, pass that URL as --base-url. An existing https://api.cloudflare.com/client/v4/accounts/<account-id>/ai/v1 URL is accepted as the default gateway. Test connection reads the account's model catalog, which proves the account ID and token permission but not an inference call.

Address models with the cloudflare/ prefix followed by Cloudflare's own model id:

ModelExampleDialect sent to Cloudflare
Workers AIcloudflare/@cf/<author>/<model>Chat Completions (Responses support varies by model)
Third-partycloudflare/openai/<model>, cloudflare/anthropic/<model>The caller's own: Chat Completions, Responses or Messages
Auto Routercloudflare/cloudflare/autoChat Completions or Responses
Dynamic Routingcloudflare/dynamic/<route-name>Chat Completions

Merido translates any other dialect through its canonical format. Workers AI models appear in the model picker from the account catalog; call third-party, Auto Router and Dynamic Routing ids directly. Client chat requests (fusion targets included) carry the selected gateway, request/org/key metadata, and — when the client sends a session header (including cf-aig-session-id) — a session id hashed with the caller's org and key, which lets the Auto Router keep one model across a turn's tool calls; response caching is partitioned by that session. Embeddings use the same account and gateway without the metadata; Merido's image, audio, moderation, OCR and rerank endpoints do not support the cloudflare provider. The Free pool add-key form cannot create a Cloudflare connection (it has no account or gateway fields): add the connection on Providers first, then use Use for Free pool.

Cloudflare API tokens are static: a 401 is reported as an upstream error under Merido's normal fallback policy rather than triggering an OAuth refresh. Rotate the token from Edit on the Providers page. A connection saved before this integration with the old …/accounts/{account_id}/ai/v1 placeholder is refused until you re-save it with a real account ID.

Upstream providers — OAuth (subscription accounts) ​

For providers that authenticate via OAuth (e.g. Claude, Codex, xAI, GitHub Copilot, Kiro), sign in interactively:

bash
merido login claude

This runs the OAuth flow locally — a browser PKCE flow for most providers, or a device-code flow for CLI providers (it prints a code and a URL). On success the tokens are stored encrypted at rest. merido refreshes them in the background.

List and remove connected OAuth accounts:

bash
merido accounts list
merido accounts remove <id>

Connecting an account to a remote gateway ​

To attach an OAuth account to a remote (e.g. Fly.io / multi-tenant) deployment, run the login locally but upload the captured tokens to the gateway, authenticated by a gateway key:

bash
merido login claude --server https://your-gateway.example --token <gateway-key>

The OAuth dance still happens on your machine (the provider redirect can only land locally); the tokens are then sealed on the gateway, scoped to your org.

Connect ChatGPT from the dashboard ​

A ChatGPT subscription (the codex provider) can be connected without the CLI: on the Providers page, pick Codex among the sign-in providers and click Get sign-in code. merido shows a one-time code; use Open OpenAI sign-in, sign in, and enter the code there. The dashboard finishes the connection on its own once you approve. Reconnect on the account's row runs the same flow for an expired account.

  • Device code login must be allowed for your ChatGPT account (ChatGPT Settings → Security), or by your workspace admin for a Business/Enterprise workspace. The code expires after 15 minutes.
  • Enter the code only on OpenAI's own page, and only for a login you started yourself. merido never asks for your OpenAI password, and the tokens never reach the browser.
  • On a multi-tenant gateway the account is private to you: other members of your organization can't see or manage it, it is never pooled, and only your personal gateway keys route through it. A virtual model that targets codex/… without pinning an account uses each caller's own ChatGPT account.
  • Disconnecting removes merido's copy of the tokens; it does not sign you out at OpenAI.

Accounts added with merido login stay shared with your organization, as before.

Browse model capabilities ​

Once a provider is connected, merido discovers the models it serves and what each one can do. The dashboard surfaces this two ways under Models (/app/models):

  • The Models tab is a searchable, sortable table of every model across all connected providers — context and output window, input modalities (text / image / video / audio / PDF), reasoning, tool-calling, structured output, temperature, and extras like prompt caching and web search.
  • Each connected provider in the Providers tab can be expanded to reveal just its own models with the same capability chips.

The capability data is synced from the open models.dev / LiteLLM rate cards and a curated table, and is exposed over the API at GET /api/model-catalog (grouped by account), GET /v1/models (per-model capabilities), and GET /v1/model_group/info (aggregated per virtual model). The router uses the same data for capability-aware routing.

Where to go next ​

Part of Merido.

© Merido Gateway. All rights reserved.