Skip to main content

Model Allowlists: Controlling Which AI Models Teams Can Access

Keeptrusts controls which AI models teams can access by binding requests to consumer groups with allowed_models, and by optionally setting a broader unified_access.allowed_models catalog-level allowlist. That means model selection becomes a gateway policy decision instead of an unreviewed client preference.

Use this page when​

  • You need engineering, marketing, research, or support teams to use different model sets behind one gateway.
  • You want to keep expensive or experimental models out of general use without changing application code.
  • You are standardizing model access as part of a team-based governance rollout.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: Technical Leaders, platform owners

The problem​

Model choice is rarely just a product decision. It affects cost, latency, data-handling posture, and the amount of review a team may need. If every client can send any model name it wants, then governance becomes reactive. The first signal is usually an unexpected spend spike, a production incident tied to a model change, or a support ticket asking why one team used a model that was never approved.

This gets more complicated in shared gateways. Different teams legitimately need different access. Research may need broader experimentation. Marketing may only need a cheaper baseline model. Customer-facing applications may need a stable, approved subset. One global default does not solve that.

The other issue is migration. When model access is uncontrolled, upgrading from one model to another becomes a client-by-client cleanup exercise. Teams pin vendor names directly, and platform owners lose the ability to stage access deliberately.

The solution​

Keeptrusts gives you two practical control layers.

At the team boundary, consumer groups map API keys to group-specific rules. One of those rules is allowed_models. That lets the gateway reject unsupported model requests at request time with a clear error, instead of silently allowing drift.

At the broader platform boundary, Unified Access can also declare allowed_models. That is useful when you want a global catalog limit even before team-level rules apply.

Those two layers serve different purposes.

  • consumer_groups[].allowed_models is the team or application control.
  • unified_access.allowed_models is the platform-wide catalog control.

Use team allowlists when the question is “which models may this team use?” Use Unified Access when the question is “which models exist in this governed environment at all?”

If you later want stable aliases instead of raw model names, pair the allowlist with Model Groups. But the allowlist is still the first control because it decides eligibility, not naming convenience.

Implementation​

The documented team-isolation flow uses consumer groups with per-group rate limits and model access controls. A minimal example looks like this:

providers:
  targets:
    - id: openai
      provider: openai
      secret_key_ref:
        env: OPENAI_API_KEY

consumer_groups:
  - name: engineering
    api_key: kt_cg_engineering_abc123
    rate_limits:
      requests_per_minute: 60
      tokens_per_day: 2000000
    allowed_models:
      - gpt-5.4-mini-mini
      - gpt-5.4-mini

  - name: marketing
    api_key: kt_cg_marketing_def456
    rate_limits:
      requests_per_minute: 30
      tokens_per_day: 500000
    allowed_models:
      - gpt-5.4-mini-mini

  - name: research
    api_key: kt_cg_research_ghi789
    rate_limits:
      requests_per_minute: 120
      tokens_per_day: 5000000
    allowed_models:
      - gpt-5.4-mini-mini
      - gpt-5.4-mini

Validate and run it:

kt policy lint --file policy-config.yaml
kt gateway run --policy-config policy-config.yaml --listen 0.0.0.0:41002

Then test the control path explicitly. Marketing is only allowed to use gpt-5.4-mini-mini, so a request for gpt-5.4-mini should fail:

curl -s -w "\nHTTP Status: %{http_code}\n" \
  http://localhost:41002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kt_cg_marketing_def456" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "Draft a press release."}]
  }'

That is the behavior you want because it is unambiguous. The gateway refuses the model request at the edge, and the allowed set is visible in config review instead of implied by convention.

If you also run Unified Access, you can add a broader top-level allowlist:

unified_access:
  enabled: true
  default_provider: openai
  allowed_models:
    - gpt-4.1
    - claude-sonnet-4-5
  cache_enabled: true

Use that layer carefully. A global allowlist is useful for platform boundaries, but it should not replace team-specific rules when different teams legitimately need different model access.

Operationally, model allowlists are one of the cleanest ways to control cost and rollout risk. If a new premium model is approved only for one team, you add it to that consumer group first. If it performs well and the economics are acceptable, you widen access deliberately instead of waiting for teams to discover it on their own.

This also gives you a simpler migration path. You can keep the approved set narrow, shift teams over group by group, and use Consumer Group Isolation or Team-Based Governance to make the access model obvious to both engineers and reviewers.

Results and impact​

The first result is predictable model governance. Teams stop treating model selection as a local application flag and start consuming an approved set defined at the gateway.

The second result is better cost control. Expensive models are available only where they are justified. Cheaper models remain the default for workloads that do not need the premium tier.

The third result is safer change management. Adding or removing model access becomes a controlled config change that can be reviewed, linted, tested, and rolled out, rather than a code change hidden inside many clients.

There is also a support benefit. When a request fails because a model is not allowed, the reason is explicit. That is much easier to debug than a vague provider-side error or an undocumented organizational rule.

Key takeaways​

  • allowed_models is the direct control for team-level model access in consumer groups.
  • Unified Access can apply a broader platform-wide allowlist when you need a governed catalog.
  • Model allowlists reduce both spend drift and rollout risk.
  • Rejecting an unauthorized model at the gateway is cleaner than discovering misuse in billing data later.
  • Pair allowlists with model groups when you want stable aliases without giving up control.

Next steps​