Skip to main content
Version: next

Dashboard: Connections

The Connections page lets you register provider accounts (credentials) once and reuse them across models. A connection holds the account (e.g. one OpenAI API key, one Anthropic OAuth login) and its endpoint; a model binds to a connection and adds its own upstream model ID, pricing, context window, and capability overrides. Editing a connection changes routing for every model bound to it, which is the whole point of the layer, see Models: Preconfigured vs. Custom connection.


Connections List​

Open Providers in the sidebar, or navigate to /dashboard/connections.

Connections List Columns​

ColumnDescription
NameUnique name of the connection, generated from the provider unless you typed one
ProviderProvider badge (e.g. openai, anthropic-oauth); a custom connection also shows the upstream provider name next to the badge
EndpointBase URL override, or a dash if using the provider default
StatusEnabled or Disabled

Each row also has a Models button (opening the Models page filtered to that connection, see Models on a Connection), and, with connections:manage, Edit and Remove buttons.

With connections:manage, clicking anywhere else on a row opens the same edit page the pencil icon does. Without it the row is inert, since there is nothing to open.

Users without connections:read see a permission-denied empty state instead of the list.

Adding a Connection​

Creating and editing a connection each live on their own dedicated page. There is no inline row expander.

  1. Click + Add Connection. This navigates to /dashboard/connections/new.
  2. Fill in the form:
    • Provider - a tile per provider, populated from GET /api/providers/descriptors and grouped by what you need to bring: Direct API (an API key), Cloud platform (Azure, Bedrock, Vertex credentials), Subscription (a paid chat plan, the OAuth providers), Browser session (the web providers), Self-hosted (Ollama and custom endpoints). One click picks the provider; picking one fills Endpoint with that provider's default address, and providers with no fixed address leave it empty
    • Provider (upstream provider name) - shown only when the provider is custom. Names the service the endpoint belongs to (e.g. deepseek); models created on this connection use it as their ID prefix, e.g. deepseek/deepseek-r1
    • Name - identifies the connection everywhere it is referenced, so it has to be unique. Leave it blank and the server names it after the provider (openai, then openai-2, openai-3, ...); the field placeholder previews the exact name you would get. A custom connection is named after its upstream instead (deepseek)
    • Endpoint (optional) - override base URL, for custom/self-hosted deployments
    • Credentials - typed fields, the same ones the model form shows for that provider (see Credential Fields)
    • Enabled - the toggle next to the page title, not a field in the form. Controls whether routing may use the connection
  3. Click Create. You are returned to the Connections list.

Secrets are never displayed once saved - the form only accepts new values, it never pre-fills or echoes existing ones. Non-secret cloud settings (AWS region and access key ID, the Azure resource/deployment/API version, the Vertex router and location) are returned by the API and do pre-fill on edit.

Credential Fields​

The credential section is rendered by the provider, not by free-form key/value rows: picking a provider swaps in exactly the fields that provider needs. It is the same component the model form uses for a custom connection, so both forms ask for the same things in the same order.

ProviderFields
API-key providers (openai, anthropic, ollama, custom, …)API Key / Token (masked, with a show/hide toggle)
anthropic-oauthSubscription OAuth Token, with instructions to generate it via claude setup-token
openai-oauthAuth file path (stored per connection and used by chat and the model Test; blank means ~/.codex/auth.json) plus a Test button that reports the account and token expiry
openai-web, anthropic-webthe session token for that provider, an optional cf_clearance, and an unofficial-provider warning
azure-openaiAzure Resource Name, Deployment ID, API Version
bedrockAWS Region, AWS Access Key ID, AWS Secret Access Key, optional Session Token
vertexGCP Project ID, Location, Service Account Key (JSON)

Endpoint URL sits above them and is optional on a connection: leaving it blank keeps the provider default. Routerly encrypts OAuth and web-session credentials server-side on save and never returns them; see Connections: Credential encryption for the field mapping.

Editing a Connection​

Click a row (or its Edit pencil icon) to navigate to /dashboard/connections/:id/edit, the same form used for creation, prefilled with the connection's current Provider, Name, Endpoint, and Enabled state. All fields are editable, including Provider. Renaming onto a name another connection already uses is rejected with Label "<name>" is already used by another connection; clearing the field regenerates the provider-based name. Secret fields start blank; leave them blank to keep the existing stored credentials unchanged, or type a new value to replace them (replacing the whole credentials object, not a per-field merge).

Change one, change all

Every model instance bound to a connection resolves its endpoint and credentials from that connection at request time. Editing a connection's endpoint or credentials here immediately changes routing for every model instance bound to it. There is no per-model override of connection-level settings. See Models: Preconfigured vs. Custom connection.

Removing a Connection​

Click the Remove (trash) icon. You will be asked to confirm; the dialog warns that instances bound to the connection will stop working - the API does not cascade-delete instances when a connection is deleted.

Connections Created from the Model Form​

Registering or editing a model with Custom credentials (see Models: Preconfigured vs. Custom connection) does not bypass the connection layer. Routerly creates (or updates) a dedicated, single-model connection for it with id conn-for-<model-id> (named after the model), and it shows up here like any other connection. Deleting that model also removes its dedicated connection, provided no other instance references it.


Models on a Connection​

The Models button on a connection row opens /dashboard/models?connection=<id>: the ordinary Models page with its Connection filter already set to that connection. There is no separate per-connection page, models are managed in one place whichever way you get there.

From that filtered list, + Add Model carries the filter into the form (/dashboard/models/new?connection=<id>), so the new model is bound to the same connection without picking it again. Pricing, context window, and capabilities are set on the model, see Models.