Groq
Login

Model Permissions

Limit which models can be used at the organization and project level. When a request attempts to use a restricted model, the API returns a 403 error.

How It Works

Configure model permissions using either "Only Allow" or "Only Block" strategies:

Only Allow

When you only allow specific models, all other models are blocked.

Example: Only allow llama-3.3-70b-versatile and llama-3.1-8b-instant → all other models are blocked.

Only Block

When you only block specific models, all other models remain available.

Example: Only block openai/gpt-oss-120b → all other models remain available.

Organization and Project Level Permissions

You can configure model permissions on either your organization, project, or both. These permissions cascade from the organization to the project, meaning that the project can only configure model permissions within the models which are allowed by the organization-level permissions.

Organization Level Permissions

Members of the organization with the Owner role can configure model permissions at the organization level.

Project Level Permissions

Members of the organization with either the Developer or Owner role can configure model permissions at the project level.

Cascading Permissions

Permissions cascade from organization to project level. Organization settings always take precedence.

How it works:

  1. Organization Check First: The system checks if the model is allowed at the org level

    • If blocked at org level → request rejected
    • If allowed at org level → proceed to project check

  2. Project Check Second: The system checks if the model is allowed at the project level

    • If blocked at project level → request rejected
    • If allowed at project level → request proceeds

Key point: Projects can only work with models that are available after org-level filtering. They can only allow a subset of what the org allows, or block a subset of what the org allows. A model blocked at the org level cannot be enabled at the project level.

See the examples below for more details.

Configuring Model Permissions

At the Organization Level

  1. Go to Settings → Organization → Limits
  2. Choose Only Allow or Only Block
  3. Select which models to allow or block
  4. Click Save

At the Project Level

  1. Select your project from the project selector
  2. Go to Settings → Projects → Limits
  3. Choose Only Allow or Only Block
  4. Select which models to allow or block
    • Only Allow: Choose from models available after org-level filtering
    • Only Block: Choose from models available after org-level filtering
  5. Click Save

Error Responses

Requests to restricted models return a 403 error with specific error codes depending on where the block occurred.

Organization-Level Block

When a model is blocked at the organization level:

JSON
{
  "error": {
    "message": "The model `openai/gpt-oss-120b` is blocked at the organization level. Please have the org admin enable this model in the org settings at https://console.groq.com/settings/limits",
    "type": "permissions_error",
    "code": "model_permission_blocked_org"
  }
}

Project-Level Block

When a model is blocked at the project level:

JSON
{
  "error": {
    "message": "The model `openai/gpt-oss-120b` is blocked at the project level. Please have a project admin enable this model in the project settings at https://console.groq.com/settings/project/limits",
    "type": "permissions_error",
    "code": "model_permission_blocked_project"
  }
}

Common Use Cases

  • Compliance: Restrict models that don't meet your data handling requirements
  • Cost Control: Limit access to higher-cost models for specific teams
  • Environment Isolation: Different model access for dev, staging, and production
  • Team Access: Give teams access to specific models based on their needs

Examples

Scenario 1: Org permissions only

  • Org: Only Allow llama-3.3-70b-versatile, llama-3.1-8b-instant, openai/gpt-oss-120b
  • Project: No restrictions

Result: Project can use llama-3.3-70b-versatile, llama-3.1-8b-instant, openai/gpt-oss-120b; all other models are blocked by the organization.


Scenario 2: Project permissions only

  • Org: No restrictions (all models available)
  • Project: Only Block openai/gpt-oss-120b

Result: Project can use all models except openai/gpt-oss-120b.


Scenario 3: Only Allow org → Only Allow subset on project

  • Org: Only Allow llama-3.3-70b-versatile, llama-3.1-8b-instant, openai/gpt-oss-120b
  • Project: Only Allow llama-3.3-70b-versatile, llama-3.1-8b-instant

Result: Project can use llama-3.3-70b-versatile and llama-3.1-8b-instant, as the project permissions narrow it down. The organization allowed openai/gpt-oss-120b is blocked by the project. All other models are blocked by the organization.


Scenario 4: Only Allow org → Block subset on project

  • Org: Only Allow llama-3.3-70b-versatile, llama-3.1-8b-instant, openai/gpt-oss-120b
  • Project: Only Block openai/gpt-oss-120b

Result: Project can use llama-3.3-70b-versatile and llama-3.1-8b-instant, as the project blocks openai/gpt-oss-120b from the organization's allowed set. All other models are blocked by the organization.


Scenario 5: Only Block org → Only Allow subset on project

  • Org: Only Block openai/gpt-oss-120b, openai/gpt-oss-20b
  • Project: Only Allow llama-3.3-70b-versatile, llama-3.1-8b-instant

Result: Project can only use llama-3.3-70b-versatile and llama-3.1-8b-instant, as the project only allows a subset from the organization's allowed set. All other models are blocked by the project.


Scenario 6: Only Block org → Block more on project

  • Org: Only Block openai/gpt-oss-120b
  • Project: Only Block llama-3.3-70b-versatile

Result: Project blocked from using both openai/gpt-oss-120b and llama-3.3-70b-versatile. The project level permissions combine with the organization-level permissions to block both models. All other models are available.

FAQ

Can I configure different permission strategies for different projects?

Yes, each project can have its own "only allow" or "only block" strategy. However, all project permissions are limited by organization-level settings.

What happens if I block all models?

All API requests will be rejected with a 403 permissions_error.

Can I temporarily disable model permissions?

Yes, you can modify or remove permission settings at any time. Changes take effect immediately.

Do model permissions affect existing API keys?

Yes, permissions apply to all API requests regardless of which API key is used. Restrictions are based on the organization and project, not the API key.

Can a project enable a model that's blocked at the org level?

No, organization-level blocks always take precedence. Projects can only further restrict access, not expand it.



Need help? Contact our support team at [email protected] or visit our developer community.

Was this page helpful?