How to Restrict OpenAI Plugins to Specific Products Like CODEX

Restrict OpenAI plugins to specific products by adding a "products" (or "compatible_products") array to the manifest file at plugins/<plugin-name>/.codex-plugin/plugin.json, listing only the compatible product identifiers such as "CODEX".

The openai/plugins repository manages plugin visibility through JSON manifest files that define product compatibility. By configuring the "products" field in your plugin's manifest, you can precisely control whether your plugin appears exclusively in CODEX, ChatGPT, DALL·E, or any combination of OpenAI products.

Understanding the Plugin Manifest Structure

Every plugin in the openai/plugins repository stores its configuration in a manifest file located at plugins/<plugin-name>/.codex-plugin/plugin.json. This JSON file declares the plugin's metadata, host endpoints, authentication scheme, and—crucially—its product restrictions. The top-level "products" array acts as a whitelist that determines which OpenAI product contexts can load and execute the plugin. For example, the repository includes working implementations like plugins/quartr/.codex-plugin/plugin.json that demonstrate this schema in production.

Configuring Product Restrictions in plugin.json

To enforce product-level restrictions, populate the "products" array with the exact product identifiers used by the OpenAI platform. Omitting this field or leaving it empty may result in unrestricted access or rejection depending on the runtime's default policy.

Restricting to a Single Product

To limit your plugin exclusively to the CODEX product, include only "CODEX" in the products array:

{
  "name": "codex‑assistant",
  "description": "Provides advanced code suggestions for CODEX",
  "version": "1.0.0",
  "products": ["CODEX"],
  "host": "https://codex‑assistant.example.com",
  "auth": { "type": "none" },
  "api": {
    "type": "openapi",
    "url": "./openapi.yaml"
  }
}

When the marketplace loader processes this manifest, it indexes the plugin exclusively under the CODEX product identifier, filtering it out from all other product contexts.

Supporting Multiple Products

To allow your plugin to function across both CODEX and ChatGPT while excluding other products, enumerate multiple identifiers:

{
  "name": "multi‑product‑helper",
  "description": "Shared utilities for CODEX and ChatGPT",
  "version": "0.3.2",
  "products": ["CODEX", "CHATGPT"],
  "host": "https://multi‑helper.example.com",
  "auth": { "type": "service_http" },
  "api": {
    "type": "openapi",
    "url": "./openapi.yaml"
  }
}

The runtime validates the current product context against this whitelist before executing any plugin functionality.

How Product Restrictions Work Internally

The OpenAI platform enforces manifest restrictions through a three-phase validation pipeline:

Marketplace Indexing

During the indexing phase, the marketplace loader scans every plugins/*/.codex-plugin/plugin.json in the repository. It compiles a lookup table that maps each plugin identifier to its allowed product identifiers based on the "products" array. This index determines which plugins appear in each product's plugin store.

Runtime Validation

When a user invokes a plugin, the runtime extracts the product context from the X‑OpenAI‑Product request header. The system checks this value against the plugin's manifest "products" array. If the header value matches any listed identifier, the plugin loads; otherwise, the request is blocked.

Error Handling

If the product identifier in the request header does not appear in the plugin's "products" array, the runtime returns a 403 Forbidden response with a message indicating that the plugin is unavailable for the requested product. This prevents cross-product execution of restricted plugins.

Key Files for Product Compatibility

Several files work together to define plugin behavior and restrictions:

• README.md – Provides the high-level repository overview and explains the plugin directory structure and manifest purpose.
• plugins/<plugin>/.codex-plugin/plugin.json – The primary manifest containing the "products" restriction array.
• plugins/<plugin>/.app.json – Optional runtime configuration that may complement product restrictions with environment variables.
• plugins/<plugin>/openapi.yaml – The OpenAPI specification referenced by the manifest that defines the plugin's API endpoints.

Summary

• The "products" array in plugins/<plugin-name>/.codex-plugin/plugin.json controls which OpenAI products can access your plugin.
• Valid identifiers include "CODEX", "CHATGPT", and other OpenAI product codes.
• The platform returns 403 Forbidden when a plugin is requested from an unauthorized product context.
• Product restrictions are enforced during marketplace indexing and runtime validation via the X‑OpenAI‑Product header.

Frequently Asked Questions

What is the exact file path for the plugin manifest?

The manifest file is located at plugins/<plugin-name>/.codex-plugin/plugin.json within the openai/plugins repository. This file contains the "products" array that governs product compatibility.

Can I restrict a plugin to multiple products while excluding others?

Yes, include all allowed product identifiers in the "products" array. Any product not explicitly listed in the array will be automatically excluded from accessing the plugin.

What happens if the products field is missing from the manifest?

If the "products" field is omitted, the plugin may default to being available for all products or be rejected by the platform depending on the specific runtime configuration. Explicitly defining the "products" array is the recommended approach for predictable access control.

Are product identifiers case-sensitive?

Yes, product identifiers are case-sensitive. Use uppercase strings such as "CODEX" and "CHATGPT" as demonstrated in the repository examples like plugins/quartr/.codex-plugin/plugin.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}