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

> Discover the two possible string values for policy.authentication in OpenAI Plugins: ON_INSTALL and ON_USE. Learn how to configure authentication for your plugins.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: api-reference
- Published: 2026-09-12

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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:

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

```

Authentication performed on each use:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`.