Open WebUI

Open WebUI connects to Actualyze as an OpenAI API connection. An administrator adds the OpenAI-compatible endpoint and an Actualyze API key in Open WebUI's admin settings, Open WebUI reads the key's model list from Actualyze, and the administrator then chooses which of those models the instance's users can see.

#Before you start

• An Actualyze API key with the inference scope and read-write permission. Workspace Admins, Members and FinOps Managers who belong to a team can create one: in the Actualyze app, select API Keys under ADMIN in the sidebar (every role that can hold keys sees this page, not only admins), then select Create API Key. Keep the default Read & Write permission.
• An administrator account on the Open WebUI instance. Connections are admin settings.
• At least one model in your workspace that your key can call.

#Install

If you don't run Open WebUI yet, its quick start covers the install options.

#Connect to Actualyze

1. From your user menu, choose Settings, then select Connections in the Admin section. Admin Panel → Settings opens the same window.
2. Check that OpenAI API is switched on, then select + (Add Connection) next to Manage OpenAI API Connections.
3. In URL, enter https://app.actualyze.ai/openai/v1. Keep the /openai/v1 suffix; Open WebUI appends /models and /chat/completions itself.
4. Leave Auth on Bearer and paste your Actualyze API key into API Key.
5. Optionally, select Verify Connection (the circular-arrows icon beside the URL). It asks Actualyze for the key's model list, so Server connection verified means the URL is right and Actualyze accepted the key. Saving alone doesn't test the connection.
6. Select Save. The connection takes effect right away.

Leave the other fields at their defaults: Connection Type External, API Type Chat Completions, and no Model IDs under Advanced.

#Choose a model

You don't list models anywhere. With Model IDs empty, Open WebUI reads the key's model list from Actualyze, so the chat model picker shows the models the key can call, Virtual Models and catalog models alike, by their IDs. The list is empty if the key's team can't call any model yet.

Models from a new connection start out private in Open WebUI: administrators see them in the picker, other users don't. To share one, open Settings → Admin → Models, open the model's ⋯ menu and choose Make Public, or open the model and use Access to share it with groups. Setting BYPASS_MODEL_ACCESS_CONTROL=true on the Open WebUI server shows every model to every user instead.

Model IDs, under Advanced on the connection, is an optional allowlist. Once it has an entry, Open WebUI stops reading the list from Actualyze and offers exactly the IDs you entered. Enter the catalog model ID or Virtual Model slug exactly as Actualyze lists it, without adding a provider/ prefix of your own. After a successful Verify Connection, the field suggests the IDs Actualyze returned.

• An administrator can hide a catalog model from the listing while leaving it callable. Adding it under Model IDs reaches it, but the picker then offers only the IDs you list.
• A Virtual Model missing from the listing isn't callable with that key at all. Adding it under Model IDs won't make it answer.

Open WebUI also makes background requests of its own, such as chat titles, tags and follow-up suggestions. By default they run on the chat's model, through the same key and budget. To keep them cheap, pick a small model as External Task Model in Settings → Admin → Interface.

#Troubleshooting

• 402: a spend limit stopped the request before any model ran, so nothing was charged. The message says which limit: usually the key's budget, or the key's own monthly limit.
• 401: the key was rejected. It may be mistyped, revoked or expired, lack the inference scope, or belong to someone who is no longer on the key's team.
• 403: the request was refused. If the message says read-write permission is required, the key is read-only; create a read-write key. Otherwise your team can't use the model you asked for; check its access in the Model Catalog or pick another.
• 402 saying Budget required: the key's budget was deleted, archived or retired, or you no longer have access to it. Create a new key bound to a budget you can use.
• Administrators see models but other users see none: the models are still private in Open WebUI. Make them public or share them with groups in Settings → Admin → Models.
• Empty model picker for an administrator: the key's team has no model it can call. Ask a workspace admin for access, or request a model from the Model Catalog. A callable catalog model that is hidden from the listing also stays out; add it under Model IDs.
• The connection saves but serves nothing: check the URL. It must end in /openai/v1. Verify Connection on the connection tests the URL and key.
• A model you just added in Actualyze doesn't appear: if Cache Base Model List is on in Settings → Admin → Connections, Open WebUI rereads the list only at startup, when you save connection settings, or when you select Refresh next to that switch.
• Model "<id>" not found: an entry under Model IDs doesn't match a catalog model or Virtual Model your workspace serves.
• A user's own connection under Settings → Connections fails with OpenAI: Network Problem: these personal Direct Connections call Actualyze from the user's browser, which Actualyze doesn't accept from other sites. Use the admin connection instead.

#Reference

Requests you cancel mid-stream still draw down the usage they consumed.

For Open WebUI's other connection settings and how it manages users and models, see Open WebUI's guide to connecting an OpenAI-compatible provider.