Skip to content

Model Access Groups

Learn how to control which LLM models your clients can access using model access groups.

What are Model Access Groups?

Model Access Groups are collections of model aliases that define which LLMs a team can use. They provide granular access control and enable tiered pricing strategies.

Built on LiteLLM

SaaS LiteLLM uses LiteLLM for routing to 100+ LLM providers. Model access groups control which of these providers and models your teams can access.

Key Benefits: - ✅ Control costs by limiting expensive models - ✅ Create pricing tiers (Basic, Pro, Enterprise) - ✅ Grant access to specific providers (OpenAI, Anthropic, etc.) - ✅ Simplify team management - ✅ Implement progressive access upgrades

How Model Access Groups Work

Team → Access Groups → Model Aliases → Actual LLM Models

Example: 

Team: "acme-prod"
  └── Access Groups: ["gpt-models", "claude-models"]
       ├── gpt-models
       │    ├── gpt-4 → openai/gpt-4
       │    └── gpt-3.5-turbo → openai/gpt-3.5-turbo
       │
       └── claude-models
            ├── claude-3-opus → anthropic/claude-3-opus-20240229
            └── claude-3-sonnet → anthropic/claude-3-sonnet-20240229

The team can now use models: gpt-4, gpt-3.5-turbo, claude-3-opus, claude-3-sonnet

Learn more about model aliases

Creating Model Access Groups

Model Access Groups Model Access Groups interface - control which models teams can access

Via Admin Dashboard

  1. Navigate to Model Access
  2. Click "Model Access" in sidebar

  3. Click "Create Access Group"

  4. Fill in Details

  5. Group Name: gpt-models (lowercase, hyphens)
  6. Description: "OpenAI GPT models"

  7. Model Aliases: Select models to include

  8. Save

  9. Click "Create"
  10. Group is ready to assign to teams

Via API

curl -X POST http://localhost:8003/api/model-access-groups/create \
  -H "Content-Type: application/json" \
  -d '{
    "group_name": "gpt-models",
    "description": "OpenAI GPT models",
    "model_aliases": ["gpt-4", "gpt-3.5-turbo", "gpt-4-turbo"]
  }'

Response: 

{
  "group_name": "gpt-models",
  "description": "OpenAI GPT models",
  "model_aliases": [
    "gpt-4",
    "gpt-3.5-turbo",
    "gpt-4-turbo"
  ],
  "created_at": "2024-10-14T12:00:00Z"
}

Common Access Group Setups

Setup 1: By Provider

Group models by AI provider:

OpenAI Models: 

{
  "group_name": "openai-models",
  "description": "All OpenAI models",
  "model_aliases": [
    "gpt-4",
    "gpt-4-turbo",
    "gpt-3.5-turbo"
  ]
}

Anthropic Models: 

{
  "group_name": "anthropic-models",
  "description": "All Anthropic Claude models",
  "model_aliases": [
    "claude-3-opus",
    "claude-3-sonnet",
    "claude-3-haiku"
  ]
}

Google Models: 

{
  "group_name": "google-models",
  "description": "Google Gemini models",
  "model_aliases": [
    "gemini-pro",
    "gemini-1.5-pro"
  ]
}

Setup 2: By Pricing Tier

Group models by cost/capabilities for tiered pricing:

Basic Tier (Fast & Cheap): 

{
  "group_name": "basic-models",
  "description": "Fast, cost-effective models",
  "model_aliases": [
    "gpt-3.5-turbo",
    "claude-3-haiku"
  ]
}

Professional Tier (Balanced): 

{
  "group_name": "pro-models",
  "description": "Balanced performance and cost",
  "model_aliases": [
    "gpt-4-turbo",
    "claude-3-sonnet",
    "gemini-pro"
  ]
}

Enterprise Tier (Most Capable): 

{
  "group_name": "enterprise-models",
  "description": "Most capable models",
  "model_aliases": [
    "gpt-4",
    "claude-3-opus",
    "gemini-1.5-pro"
  ]
}

Setup 3: By Use Case

Group models by intended application:

Chat/Conversational: 

{
  "group_name": "chat-models",
  "description": "Optimized for conversation",
  "model_aliases": [
    "gpt-3.5-turbo",
    "claude-3-sonnet"
  ]
}

Analysis/Complex Tasks: 

{
  "group_name": "analysis-models",
  "description": "Complex reasoning and analysis",
  "model_aliases": [
    "gpt-4",
    "claude-3-opus"
  ]
}

Fast Tasks: 

{
  "group_name": "fast-models",
  "description": "Quick responses for simple tasks",
  "model_aliases": [
    "gpt-3.5-turbo",
    "claude-3-haiku"
  ]
}

Assigning Access Groups to Teams

During Team Creation

curl -X POST http://localhost:8003/api/teams/create \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_acme",
    "team_id": "acme-prod",
    "team_alias": "Production",
    "access_groups": ["gpt-models", "claude-models"],
    "credits_allocated": 1000
  }'

Update Existing Team

curl -X PUT http://localhost:8003/api/teams/acme-prod \
  -H "Content-Type: application/json" \
  -d '{
    "access_groups": ["gpt-models", "claude-models", "gemini-models"]
  }'

Via Dashboard: 1. Navigate to team 2. Click "Edit Access Groups" 3. Select/deselect groups 4. Click "Save"

Viewing Access Groups

List All Access Groups

Via Dashboard: - Navigate to "Model Access" - See all access groups with model counts

Via API: 

curl http://localhost:8003/api/model-access-groups

Response: 

{
  "access_groups": [
    {
      "group_name": "gpt-models",
      "description": "OpenAI GPT models",
      "model_count": 3,
      "team_count": 15
    },
    {
      "group_name": "claude-models",
      "description": "Anthropic Claude models",
      "model_count": 3,
      "team_count": 8
    }
  ]
}

View Access Group Details

curl http://localhost:8003/api/model-access-groups/gpt-models

Response: 

{
  "group_name": "gpt-models",
  "description": "OpenAI GPT models",
  "model_aliases": [
    {
      "alias": "gpt-4",
      "litellm_model": "openai/gpt-4",
      "description": "Most capable GPT-4 model"
    },
    {
      "alias": "gpt-3.5-turbo",
      "litellm_model": "openai/gpt-3.5-turbo",
      "description": "Fast and efficient"
    }
  ],
  "teams_with_access": [
    "acme-prod",
    "techco-dev",
    "client-staging"
  ]
}

Managing Access Groups

Add Models to Group

curl -X POST http://localhost:8003/api/model-access-groups/gpt-models/add-models \
  -H "Content-Type: application/json" \
  -d '{
    "model_aliases": ["gpt-4-vision"]
  }'

Remove Models from Group

curl -X POST http://localhost:8003/api/model-access-groups/gpt-models/remove-models \
  -H "Content-Type: application/json" \
  -d '{
    "model_aliases": ["gpt-3.5-turbo"]
  }'

Delete Access Group

Warning

Deleting an access group will remove it from all teams. Teams will lose access to models in this group unless they have the models through other access groups.

curl -X DELETE http://localhost:8003/api/model-access-groups/old-models

Pricing Strategies Using Access Groups

Strategy 1: Tiered Plans

Offer different plans with different model access:

Starter Plan - $99/month 

{
  "access_groups": ["basic-models"],
  "credits_allocated": 1000
}
- Access: GPT-3.5-turbo, Claude 3 Haiku - Best for: Simple tasks, high volume

Professional Plan - $299/month 

{
  "access_groups": ["basic-models", "pro-models"],
  "credits_allocated": 5000
}
- Access: All basic + GPT-4-turbo, Claude 3 Sonnet - Best for: Complex tasks, balanced performance

Enterprise Plan - $999/month 

{
  "access_groups": ["basic-models", "pro-models", "enterprise-models"],
  "credits_allocated": 20000
}
- Access: All models including GPT-4, Claude 3 Opus - Best for: Maximum capabilities

Strategy 2: Provider-Based Pricing

Charge based on provider access:

OpenAI Only - $149/month 

{
  "access_groups": ["openai-models"],
  "credits_allocated": 2000
}

Multi-Provider - $299/month 

{
  "access_groups": ["openai-models", "anthropic-models", "google-models"],
  "credits_allocated": 5000
}

Strategy 3: Use Case Bundles

Bundle models by intended use:

Chat Bundle - $199/month 

{
  "access_groups": ["chat-models"],
  "credits_allocated": 3000
}

Analysis Bundle - $399/month 

{
  "access_groups": ["analysis-models", "chat-models"],
  "credits_allocated": 5000
}

Team Model Access Workflow

When Team Makes API Call

  1. Team sends request: 

    POST /api/jobs/{job_id}/llm-call
{
  "model": "gpt-4",
  "messages": [...]
}

  2. SaaS API checks:

  3. Does team have "gpt-4" in any access group? ✅
  4. Is team active? ✅

  5. Does team have credits? ✅

  6. SaaS API resolves:

  7. gpt-4 → openai/gpt-4 (via model alias)

  8. Routes to LiteLLM:

  9. LiteLLM routes to actual OpenAI API

  10. Response returns through chain

  11. If access denied: 

    {
  "error": "Model access denied",
  "message": "Team does not have access to model 'gpt-4'",
  "available_models": ["gpt-3.5-turbo", "claude-3-haiku"]
}

Common Workflows

Workflow 1: Upgrade Team to Higher Tier

Client wants access to more powerful models:

# 1. Check current access
curl http://localhost:8003/api/teams/acme-prod

# 2. Update access groups
curl -X PUT http://localhost:8003/api/teams/acme-prod \
  -d '{
    "access_groups": ["basic-models", "pro-models", "enterprise-models"]
  }'

# 3. Add more credits for higher usage
curl -X POST http://localhost:8003/api/credits/add \
  -d '{
    "team_id": "acme-prod",
    "amount": 10000
  }'

Workflow 2: Create Custom Access for Enterprise Client

Enterprise client wants specific models:

# 1. Create custom access group
curl -X POST http://localhost:8003/api/model-access-groups/create \
  -d '{
    "group_name": "acme-custom",
    "description": "Custom models for ACME Corp",
    "model_aliases": [
      "gpt-4",
      "claude-3-opus",
      "gemini-1.5-pro"
    ]
  }'

# 2. Assign to team
curl -X PUT http://localhost:8003/api/teams/acme-prod \
  -d '{
    "access_groups": ["acme-custom"]
  }'

Workflow 3: Temporarily Grant Access for Testing

Client wants to test a new model:

# 1. Add access group temporarily
curl -X PUT http://localhost:8003/api/teams/acme-dev \
  -d '{
    "access_groups": ["current-models", "experimental-models"]
  }'

# 2. Monitor usage

# 3. Remove after testing
curl -X PUT http://localhost:8003/api/teams/acme-dev \
  -d '{
    "access_groups": ["current-models"]
  }'

Best Practices

Naming Conventions

Access Group Names: - Use lowercase with hyphens - Be descriptive: gpt-models, premium-models, chat-optimized - Use consistent prefixes for organization: tier-basic, tier-pro, tier-enterprise

Organization

  1. Start with Provider Groups
  2. Create one group per provider (OpenAI, Anthropic, Google)

  3. Easy to understand and manage

  4. Add Tier Groups as You Grow

  5. Basic, Professional, Enterprise

  6. Maps to pricing plans

  7. Create Use Case Groups for Specific Clients

  8. Custom bundles for enterprise clients
  9. Special access for partners

Access Control

  1. Principle of Least Privilege
  2. Start teams with minimal access
  3. Upgrade as needed

  4. Don't grant all models by default

  5. Separate Dev and Prod

  6. Dev teams: cheaper models for testing

  7. Prod teams: full access to needed models

  8. Monitor and Adjust

  9. Track which models teams actually use
  10. Remove unused access groups
  11. Identify upgrade opportunities

Cost Management

  1. Group by Cost
  2. Create "expensive-models" group
  3. Restrict to paying customers only

  4. Monitor usage of costly models

  5. Gradual Rollout

  6. New models → small test group first
  7. Monitor costs and performance

  8. Expand access gradually

  9. Sunset Old Models

  10. Remove deprecated models from groups
  11. Notify teams before removal
  12. Provide migration path

Troubleshooting

Team Can't Access Model

Problem: Client reports "Model access denied" for gpt-4

Solutions: 1. Check team's access groups: 

curl http://localhost:8003/api/teams/acme-prod

  1. Check if any access group contains the model: 

    curl http://localhost:8003/api/model-access-groups/gpt-models

  2. Add missing access group: 

    curl -X PUT http://localhost:8003/api/teams/acme-prod \
  -d '{"access_groups": ["existing-groups", "gpt-models"]}'

Model Alias Not Found

Problem: Access group won't accept model alias

Solutions: 1. Verify model alias exists: 

curl http://localhost:8003/api/model-aliases

  1. Create model alias if missing: 

    curl -X POST http://localhost:8003/api/model-aliases/create \
  -d '{
    "alias": "gpt-4",
    "litellm_model": "openai/gpt-4",
    "description": "GPT-4"
  }'

  2. Add to access group: 

    curl -X POST http://localhost:8003/api/model-access-groups/gpt-models/add-models \
  -d '{"model_aliases": ["gpt-4"]}'

Access Group Changes Not Taking Effect

Problem: Updated access groups but team still can't access model

Solutions: 1. Verify update succeeded: 

curl http://localhost:8003/api/teams/acme-prod

  1. Check model is in the access group: 

    curl http://localhost:8003/api/model-access-groups/gpt-models

  2. Restart SaaS API server if needed (rare): 

    docker compose restart saas-api

Example: Complete Client Onboarding with Access Control

# 1. Create organization
curl -X POST http://localhost:8003/api/organizations/create \
  -d '{
    "organization_id": "org_newclient",
    "name": "New Client Inc"
  }'

# 2. Create access groups (if not exists)
curl -X POST http://localhost:8003/api/model-access-groups/create \
  -d '{
    "group_name": "starter-models",
    "description": "Starter tier models",
    "model_aliases": ["gpt-3.5-turbo", "claude-3-haiku"]
  }'

# 3. Create team with access
curl -X POST http://localhost:8003/api/teams/create \
  -d '{
    "organization_id": "org_newclient",
    "team_id": "newclient-prod",
    "team_alias": "Production",
    "access_groups": ["starter-models"],
    "credits_allocated": 1000
  }'

# 4. Share virtual key with client
# (From response above)

# 5. Later: Upgrade to pro tier
curl -X PUT http://localhost:8003/api/teams/newclient-prod \
  -d '{
    "access_groups": ["starter-models", "pro-models"]
  }'

# 6. Add more credits
curl -X POST http://localhost:8003/api/credits/add \
  -d '{
    "team_id": "newclient-prod",
    "amount": 5000
  }'

Next Steps

Now that you understand model access groups:

  1. Configure Model Aliases - Set up the actual models
  2. Create Teams - Assign access groups to teams
  3. Monitor Usage - Track which models are used most
  4. Best Practices - Advanced access control patterns

Quick Reference

Create Access Group

POST /api/model-access-groups/create
{
  "group_name": "gpt-models",
  "description": "OpenAI GPT models",
  "model_aliases": ["gpt-4", "gpt-3.5-turbo"]
}

Assign to Team

PUT /api/teams/{team_id}
{
  "access_groups": ["gpt-models", "claude-models"]
}

Add Models to Group

POST /api/model-access-groups/{group_name}/add-models
{
  "model_aliases": ["new-model"]
}

View Group Details

GET /api/model-access-groups/{group_name}