Model access

Model access decides which AI models exist for whom. Nothing is usable by default: a model reaches a person only when its provider connection is enabled, the model is in the catalog and enabled, it is assigned at a scope that applies to the person, and it is allowed for the request's data classification.

1. Connect a provider

Open Models > Providers and keys and add a connection, or use the API:

curl -sS -X POST "$KEYSTONE_URL/api/v1/models/providers" \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "Anthropic production", "kind": "anthropic", "base_url": "https://api.anthropic.com", "region": "us"}'

curl -sS -X PUT "$KEYSTONE_URL/api/v1/models/providers/$PROVIDER_ID/key" \
  -H "Authorization: Bearer $KEY_ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"key": "<provider API key>"}'

Connection kinds are anthropic, openai, google, azure_openai, bedrock, vertex, openai_compatible and ollama. Azure takes config.azure_api_version; Vertex takes config.vertex_project and config.vertex_location.

Keys are write-only

Keys are stored in Govern Vault and never returned. Responses show only set, the last four characters (hint), a version and the rotation time. Setting, rotating and deleting a key needs models:keys, separate from configuring the connection (models:admin), so the person who handles keys need not manage policy.

Changing a connection's base URL, region or settings drops its stored key (audited models.provider.key.removed, reason endpoint_changed), so nobody can redirect a key to a host they control. Key changes are refused while the vault is sealed.

Outbound connections

Every upstream request goes through Govern's outbound guard: loopback, private, link-local, carrier-grade NAT and cloud metadata addresses are refused at connect time, and no redirect is followed. The operator of a self-hosted installation can open private networks for model servers with NI_AUTH_MODELS_PRIVATE_NETWORKS (comma-separated CIDR prefixes or addresses; refused on the hosted service). With it, openai_compatible and ollama connections are confined to those networks and their models count as self-hosted. Without it they reach public addresses only and do not count as self-hosted.

Provider health

POST /api/v1/models/providers/{id}/health/check (models:admin) probes a connection now; GET /api/v1/models/providers/{id}/health (models:view) shows the last 20 probes and the circuit state of its models. The console page is Models > Provider health. A scheduled probe runs only when the operator sets NI_AUTH_MODELS_PROVIDER_HEALTH_SCHEDULE (for example @every 15m).

2. Add models to the catalog

Open Models > Model catalog, or POST /api/v1/models/catalog (models:write). Govern does not discover models from providers: you enter each model and its prices, which keeps the catalog air-gap safe and prices under your control.

PUT /api/v1/models/catalog/{id}/fallbacks sets a model's fallback chain (up to 20). Each fallback is decided again from scratch, so a fallback never reaches a model the caller may not use.

3. Assign models

Assignments allow or deny a model at a scope. Open the model in the catalog, or use PUT /api/v1/models/assignments (models:write) with scope_kind (org, team or project), scope_id, model_id and effect (allow or deny).

• A model is usable when it is allowed at a scope that applies to the caller and denied at none. A deny at any applicable scope wins.
• Applicable scopes are the organisation, every team the caller belongs to, and the request's project when the caller is a member of it.
• Leaving out the project never loosens a project's rules. A request without a project gets the denies of every project the caller belongs to, and is classified at the strictest scope the caller works in.
• To give one project a model the organisation does not want generally, allow it on that project only.

Defaults

PUT /api/v1/models/defaults sets a default model per use (chat, agent, completion, embedding) at a scope. The most specific scope wins: project, then team, then organisation. A default the caller may not use is skipped.

4. Set the routing policy

Models > Routing edits the organisation's policy (GET/PUT /api/v1/models/policy; models:admin to change):

Classification

Each request is classified from its project: the strictest of project, team, department and organisation. A client may raise the classification with X-Keystone-Classification, never lower it. A project with compliance frameworks set is regulated. Then:

1. The model's max_classification must be at least the request's classification.
2. The organisation's rule for that classification must hold.

require_project: regulated refuses a request without a project when the caller's strictest classification is confidential or restricted, or when the caller belongs to a regulated project. always refuses every request without one. An API key belongs to no team or project, so it is decided at the organisation root's classification.

Personal keys

With user_keys_enabled, people may store their own Anthropic, OpenAI or Google key with PUT /api/v1/models/me/keys/{provider}. The gateway uses it for catalog models on connections of that kind, only up to user_key_max_classification, only for models the organisation allowed, and only through the organisation's configured endpoint. Spend on a personal key is not counted against spend budgets (tokens are).

Permissions

Model connections are also shareable resources: a Viewer of one connection can read its configuration, a User can call models through it. See Roles and permissions.

Limits

50 provider connections, 500 catalog models, 20 fallbacks per model, 2,000 assignments, 2,000 defaults and 500 budgets per organisation.

Not supported

Bedrock models other than Anthropic models (the Converse API) and Gemini's native API are not built. Google and Vertex Gemini models are reached through their OpenAI-compatible endpoints.

Audit

Every change is audited in its own transaction. Key changes write two records, the change and a key record with the new version and hint, never the key.