What Are the Possible Values for policy.authentication in OpenAI Plugins?

The policy.authentication field in OpenAI Plugins accepts only two string values: ON_INSTALL and ON_USE.

When configuring authentication behavior for plugins in the openai/plugins repository, developers must set the policy.authentication property to control when users are prompted to authenticate. According to the marketplace plugin descriptors in the source code, this field is strictly limited to specific enum values that determine whether authentication occurs during installation or on every use.

Valid Values for policy.authentication

The policy.authentication property supports exactly two case-sensitive string values as defined in the plugin marketplace descriptors. These values dictate the timing strategy for OAuth or credential validation.

ON_INSTALL — Configures the plugin to perform authentication once during the initial installation process. When a user installs a plugin with this setting, they complete the authentication flow immediately, and subsequent uses do not require re-authentication.

ON_USE — Requires authentication each time the plugin is invoked. This setting ensures users verify their credentials or permissions every time they interact with the plugin's capabilities, providing stricter access control for sensitive operations.

Source File References

These authentication policies are defined and repeatedly validated within the marketplace plugin descriptor files located in the .agents/plugins/ directory.

According to the openai/plugins source code, the specific files establishing these valid values include:

• .agents/plugins/marketplace.json — Contains numerous plugin entries that exclusively use ON_INSTALL or ON_USE for the authentication property
• .agents/plugins/api_marketplace.json — Mirrors the marketplace structure and confirms the same two allowed authentication values across all plugin configurations

Implementation Examples

When defining your plugin manifest or marketplace entry, specify the authentication policy within the policy object using one of the two valid strings.

Authentication performed on installation:

{
  "name": "example-plugin",
  "policy": {
    "authentication": "ON_INSTALL"
  }
}

Authentication performed on each use:

{
  "name": "another-plugin",
  "policy": {
    "authentication": "ON_USE"
  }
}

Summary

• The policy.authentication field strictly accepts only ON_INSTALL or ON_USE as valid values
• ON_INSTALL authenticates users once during plugin installation and persists credentials for subsequent uses
• ON_USE mandates fresh authentication every time the plugin is accessed
• These enum values are defined in .agents/plugins/marketplace.json and .agents/plugins/api_marketplace.json
• Developers must use exactly these uppercase, case-sensitive strings when configuring plugin authentication policies

Frequently Asked Questions

What does ON_INSTALL authentication mean in OpenAI Plugins?

ON_INSTALL means the user completes the authentication flow—typically OAuth—when they first add the plugin to their environment. The credentials are stored securely and reused for all subsequent interactions, providing a seamless user experience without repeated login prompts.

What is the difference between ON_INSTALL and ON_USE?

ON_INSTALL authenticates once at setup and maintains the session across multiple uses, while ON_USE requires users to authenticate every single time they invoke the plugin. Choose ON_INSTALL for convenience and ON_USE when maximum security or fresh authorization tokens are required for each operation.

Can I use custom values for policy.authentication?

No. The openai/plugins repository validates the policy.authentication field against a strict enum containing only ON_INSTALL and ON_USE. Attempting to use other strings will result in validation failures when the plugin descriptor is processed.

Where are the valid policy.authentication values defined?

The allowed values are established in the .agents/plugins/marketplace.json and .agents/plugins/api_marketplace.json files within the openai/plugins repository. These JSON files contain the canonical plugin definitions that specify authentication must be set to either ON_INSTALL or ON_USE.

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