AI Models¶

The AI Models section holds the catalog of AI models Imbi may call. The catalog has two levels. A provider is one configured endpoint, with its own credential. A model is one model that provider serves.

The catalog is global. Every organization in the deployment shares the same providers, credentials, and models. Use Team access to limit a model to some teams.

Open the section at Admin > Global Admin > AI Models.

Drivers¶

A driver is the request shape Imbi uses to talk to a vendor. Drivers are built in. You cannot add one from the UI.

Use OpenAI-compatible for any endpoint that implements the OpenAI chat-completions API, such as vLLM, Ollama, or a gateway.

AWS Bedrock and Google Vertex AI can authenticate from the credentials of the process Imbi runs as. A provider on either driver with no stored key reports IAM role. Setting a key overrides the role for every model under that provider.

TypeSafe serves decision models, such as Jev (jev-latest). A decision model returns typed judgments and probabilities instead of text. TypeSafe has no model-list endpoint, so add each model manually.

The section lists every driver. A driver with no provider configured appears as a greyed row with a Set up action.

Add a provider¶

1. Click Add provider, or click Set up on a driver row.
2. Select the driver. The description below the field explains what it calls.
3. Enter a name. The name identifies this provider in every model list.
4. Enter the base URL. Leave the prefilled default for Anthropic and OpenAI. OpenAI-compatible requires a URL.
5. Enter the region for AWS Bedrock, or the region and project ID for Google Vertex AI.
6. Paste an API key. This field is optional. You can set the key later.
7. Enter a description. This field is optional.
8. Click Create provider.

The base URL must use http or https, must include a host, and must not embed a username or a password. Imbi rejects any other URL.

Configure one provider for each credential. To run two Anthropic keys, create two Anthropic providers, such as "Anthropic Production" and "Anthropic Research". A model cannot override its provider's key.

Manage credentials¶

Click the key icon on a provider row to open the credentials dialog.

• To set or replace a key, paste the key and click Save key. A replacement takes effect on the next request from every model under the provider.
• To remove a key, click Remove key. Models under the provider can no longer be called, unless the driver falls back to an IAM role.

Imbi encrypts the key before it stores it. The key is never returned by the API, shown in the UI, or written to a log.

The dialog and the provider row show three things instead of the key:

• Whether a key is set.
• The last four characters of the key, as ••••abcd. Use this to tell two keys apart. Keys shorter than eight characters get no hint.
• When the key was last changed.

Setting or removing a credential requires the ai_model:credentials permission. Editing a model does not grant it.

Use workload identity instead of a key¶

An Anthropic or OpenAI provider can get a short-lived token through workload identity federation, so that Imbi stores no key. The provider must use the default base URL and have no stored key. The dialog shows the workload identity target only when the plugin of the vendor (anthropic or openai) is installed and enabled. The Workload Identity Runbook gives the vendor setup.

1. Select the organization whose identity source signs the tokens. The organization needs an identity source; see Workload identity.
2. Click the key icon on the provider row.
3. In Workload identity target, enter the vendor ids of the provider:
4. Anthropic, from the Anthropic Console: {"organization_id": "...", "federation_rule_id": "...", "service_account_id": "...", "workspace_id": "..."}. workspace_id is necessary only when the rule has more than one workspace.
5. OpenAI, from the OpenAI dashboard: {"identity_provider_id": "...", "service_account_id": "..."}. The OpenAI identity provider must use the audience https://api.openai.com/v1. See the plugin README.
6. Click Use workload identity. The provider row shows Workload identity.

Imbi mints a new token for each identity JWT and renews it before it expires. Each token carries the tags imbi_org and imbi_ai_provider, so the vendor can track cost for each provider. Model discovery uses the token. To stop, click Stop using workload identity.

You need ai_model:credentials, membership of the organization, and secret_provider:write in that organization.

Imbi services¶

imbi-api, the assistant, and the Slack bot can use an Anthropic provider with workload identity instead of ANTHROPIC_API_KEY. Set these variables on imbi-api to the id of the provider:

The assistant and the Slack bot get the token from imbi-api as their own service account (imbi-assistant, imbi-slackbot). Set IMBI_ASSISTANT_API_TOKEN or IMBI_SLACKBOT_API_TOKEN on the service to the API key of that account; see Imbi service accounts. With the API key set, the service ignores ANTHROPIC_API_KEY. Without it, the service uses ANTHROPIC_API_KEY as before.

imbi-api gives a service only the token of its own provider. The request names no provider.

Add a model manually¶

Click Add model, or click the plus icon on a provider row. The dialog has two steps.

Step 1: identity¶

Step 2: limits, cost, and access¶

Every field in step 2 is optional. Leave a cost empty when the price is unknown or set by contract. Enter 0 for a self-hosted model.

Two rules apply within the catalog. A model's display name must produce a slug that is unique in the catalog. A model identifier must be unique within its provider. Imbi returns 409 when either rule fails.

Discover and import models¶

Anthropic, OpenAI, and OpenAI-compatible providers can report their own model lists. Use this instead of typing model identifiers by hand.

1. Set a credential on the provider.
2. Click the refresh icon on the provider row. You can also expand the provider and click Import from that provider.
3. Wait for the list. Imbi calls the provider with its stored key.
4. Search the list, or click Select all new.
5. Select the models to add. A model already in the catalog shows an Already configured badge and cannot be selected.
6. Click Import in the footer.

Discovery reads only. Nothing is written until you import.

Every imported model lands enabled, as Chat, and available to every team. Anthropic also supplies the context window and the maximum output tokens where it publishes them. Narrow the access and fill in the costs afterwards.

Discovery also tests the stored credential. A failure reports the driver and the HTTP status or the transport error. The provider's response body is never shown, because a provider can echo the key back inside it.

Discovery fails with a clear message in three cases. The provider has no stored credential. The driver does not support discovery. The provider rejected the call.

Team access¶

A model is available either to every team or to named teams.

• All teams makes the model available to every team in every organization. This is the default.
• Selecting one or more teams restricts the model to those teams.

Select the All teams chip to return to access for every team. The team picker lists the teams of the organization you have selected. A restricted model must name at least one team. Imbi rejects an empty team list with 422.

Deleting a team does not update the models that name it. Review restricted models after you delete a team.

Enable and disable¶

Every provider and every model carries an enabled flag.

Use the switch on a model row to enable or disable it. A disabled model keeps its configuration and disappears from every picker. Disable a model instead of deleting it when you plan to bring it back.

Delete¶

Expand the provider, click the edit icon on the model row, click Continue, then click Delete model.

To delete a provider, click the edit icon on the provider row, then click Delete provider. The button is disabled while the provider still serves models. The API (DELETE /ai-providers/{id}) returns 409 for the same condition. Delete the models first, or move them to another provider. There is no cascade, so a provider cannot take its models with it.

Permissions¶

Administrators hold all six. The Developer, Default, and Read Only roles hold ai_model:read.

POST /ai-providers/token needs a service account with a configured provider. A human administrator passes the permission check but gets 404. This is expected, not a fault.

ai_model:credentials is deliberately separate from ai_model:update. Changing a model's temperature must not imply the right to replace the production key.

See Roles and Permissions to grant these to a custom role.

Related¶

• ADR 0018: AI Model Catalog records the design and the alternatives that were rejected.
• API Configuration covers the API service settings.