Model access
By default, every project may call every model in the catalog. Four controls narrow that down, from the widest to the narrowest:
| Control | Set by | Where | What it does |
|---|---|---|---|
| External providers | Operator, then platform admin | Helm externalProviders.enabled, then Settings | Whether any call may leave the cluster. See External providers. |
| Organization model policy | Organization admin | Organizations > Settings | Keep the organization's projects off external providers, and list the only models they may name. |
| Per-project model access | Platform admin | Models, on a model | Restrict a model to named projects. |
| Agent model policy and key scopes | Project admin | The agent's policy, and a key's limits | The models one agent, or one key, may name. |
A call has to pass every control that applies to it.
Restrict a model to projects
- Open Models and choose the model.
- Turn on Restrict to specific projects and tick the projects that may use it.
- Save. You need the platform admin role.
The restriction is enforced in two places:
- The Model Gateway, on every call. A call from any other project is refused with
403and a message that names the model. Takes effect within about 15 seconds. - The API, when an agent that names the model is saved, made live or deployed in another project, and when a knowledge base uses it as its embedding model. The refusal comes while someone is looking at the agent, not as a failed run later.
A restricted model with no projects ticked can be used only by platform admins and by the platform's own system calls. The audit event says so.
Calls that belong to no project, such as a personal API key or a console user's own Playground session with a model, can use only unrestricted models, unless the caller is a platform admin.
If the access table can't be read and nothing is cached, a call to a project is refused with 503. A restriction that lifted itself whenever the database was slow wouldn't be a restriction.
On Projects, each project's Model access panel shows which models that project may call.
Organization model policy
An organization admin can set, for all the organization's projects:
- External providers off. Calls to an external model are refused with
403organization_external_providers_off. - Allowed models: the only models the projects may name. Others are refused with
403model_not_allowed_for_organization.
Refused models are also left out of GET /v1/models. If the organization policy can't be read, a call to an external model is refused with 503 organization_policy_unavailable, and a call to a model in your cluster goes ahead.
Agent model policy
Each agent can have a policy: the models it may use, whether it may use external models, and a cap on tokens per call. The Model Gateway applies it to calls made with the agent's own key, which is how code agents call models. A code agent's models.allowed in orchestrate.yaml fills it in on promotion, unless a project admin set the list by hand.
Key scopes
A project admin can give a project key or an agent key a list of allowed models. The key can name only those, and GET /v1/models lists only those for it. Others are refused with 403 model_not_in_key_scope. See Usage controls.
Policy rules
For anything these controls don't cover, write a custom policy. For example, a Deny rule on chat with a model condition stops one model for everyone, and one on deploy_model with project_id and model_id stops a model being deployed into a project. See Policy.