How to Set Up Authentication Policies for OpenAI Plugins

OpenAI plugins use a policy-driven architecture defined across three files—agents/openai.yaml, references/authentication.md, and SKILL.md—to control invocation permissions and authentication methods.

The openai/plugins repository implements a standardized approach to securing plugin skills through declarative policy files. Every skill resides under plugins/<provider>/skills/<skill>/ and requires specific configuration to define how users authenticate and whether the skill can be invoked implicitly by AI agents.

Understanding the Three-File Policy Architecture

The authentication policy for any OpenAI plugin is distributed across three mandatory components that work together to enforce security and documentation standards.

agents/openai.yaml (Invocation Policy)

This YAML file declares the OpenAI-specific invocation policy. The critical field is allow_implicit_invocation, which determines whether the skill can be triggered automatically by AI agents or must be called explicitly by name.

references/authentication.md (Method Documentation)

This markdown file catalogs supported authentication mechanisms—such as OAuth 2.0, Server-to-Server OAuth, and JWT—along with required scopes and endpoint details.

SKILL.md (Public Interface)

The skill's entry point document links to both the invocation policy and authentication reference, ensuring developers understand security requirements before integration.

Configuring the Invocation Policy

To prevent accidental activation, set allow_implicit_invocation to false in agents/openai.yaml:

# plugins/<provider>/skills/<skill>/agents/openai.yaml

policy:
  allow_implicit_invocation: false

When this flag is disabled, users must explicitly reference the skill by name (e.g., "using the Zoom skill") rather than having the AI automatically invoke it based on conversation context. The allow_implicit_invocation field is the only required policy setting, though additional fields may be introduced as the policy language evolves.

Documenting Authentication Methods

The references/authentication.md file must detail every supported authentication flow. According to the openai/plugins source structure, include:

• Supported grant types (Authorization Code, Client Credentials, JWT)
• Required scopes and permissions
• Token endpoint URLs
• Sample curl commands for token exchange

For example, the Zoom Rest-API skill at plugins/zoom/skills/rest-api/references/authentication.md outlines three distinct authentication flows with implementation details and links to official provider documentation.

Exposing Policies in SKILL.md

Every skill must reference its authentication documentation in the main SKILL.md file. Add an explicit authentication section that links to the reference file:

## Authentication

This skill supports the following authentication flows:
- [OAuth 2.0 (User-grant)](../references/authentication.md#user-grant)
- [Server-to-Server OAuth](../references/authentication.md#s2s-oauth)
- [JWT (legacy)](../references/authentication.md#jwt)

This pattern ensures developers can locate authentication requirements without examining source code, maintaining clarity across the repository.

Real-World Implementation: Zoom Plugin

The Zoom plugin demonstrates the complete policy architecture across two skills:

1. Zoom Apps SDK (plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml): Sets allow_implicit_invocation: false to require explicit skill invocation, preventing accidental triggers.

2. Rest-API (plugins/zoom/skills/rest-api/): Contains comprehensive authentication documentation at references/authentication.md and links to it from SKILL.md, covering OAuth 2.0, Server-to-Server OAuth, and legacy JWT flows.

This structure prevents unauthorized implicit invocations while providing clear guidance on implementing Zoom's authentication requirements.

Summary

• Invocation control is managed through agents/openai.yaml using the allow_implicit_invocation boolean field to toggle between explicit and implicit activation.
• Authentication methods are documented in references/authentication.md with technical specifications for OAuth 2.0, JWT, and other flows, including scopes and endpoint details.
• Developer visibility requires linking policy files in SKILL.md to ensure proper integration and security awareness.
• The three-file pattern is consistent across the openai/plugins repository, from Zoom to Airtable and Wix implementations, enabling automated validation and unified security posture.

Frequently Asked Questions

What is the purpose of allow_implicit_invocation in OpenAI plugins?

This boolean flag in agents/openai.yaml controls whether an AI agent can automatically invoke a skill based on conversation context. When set to false, users must explicitly mention the skill by name, preventing accidental activations and improving security against unintended skill triggers.

Where should authentication methods be documented in the openai/plugins repository?

Authentication methods belong in references/authentication.md within the skill directory. This file should detail OAuth grants, required scopes, token endpoints, and include sample requests. The main SKILL.md must then link to this reference to maintain the standardized documentation pattern.

Can a plugin support multiple authentication methods simultaneously?

Yes. A single skill can support multiple flows such as OAuth 2.0, Server-to-Server OAuth, and legacy JWT. Each method must be documented in references/authentication.md and listed in SKILL.md to inform developers of their integration options and security requirements.

How does the repository enforce authentication policy consistency?

The openai/plugins repository uses CI automation to validate that every skill contains the required agents/openai.yaml file with the allow_implicit_invocation field defined. Missing or malformed policy files trigger validation errors during the pull request process, ensuring all plugins maintain baseline security standards.

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