What Kind of Data Can an OpenAI Plugin Access? Capabilities, Scopes, and Security

OpenAI plugins can access user-owned data from external APIs—including documents, calendars, contacts, and third-party service records—but only within the specific scope of declared capabilities (Read, Write, Interactive) defined in the plugin manifest.

The openai/plugins repository defines a strict permission model that governs what data an OpenAI plugin can access during conversations. Each plugin declares its data access rights through a .codex-plugin/plugin.json manifest file, ensuring users understand exactly what information will be retrieved, modified, or queried before granting installation permissions.

Understanding Plugin Capabilities

The manifest file located at .codex-plugin/plugin.json (for example, plugins/zotero/.codex-plugin/plugin.json) contains a capabilities array that determines what kind of data an OpenAI plugin can access. These capabilities act as permissions gates, restricting the plugin to specific interaction patterns with external services.

Read Capability

The Read capability allows a plugin to retrieve data from external services. When enabled, the plugin can access user-owned resources such as documents, contacts, calendars, and any public or authenticated API endpoints that return structured data like JSON or CSV.

According to the source code, this capability enables queries like searching a Zotero library or fetching Stripe account information. The plugin cannot modify data with this capability alone.

Write Capability

The Write capability permits a plugin to send data to external services to create, update, or delete resources. This enables actions such as creating Jira tickets, adding events to Google Calendar, or updating contact records.

The manifest in plugins/zotero/.codex-plugin/plugin.json demonstrates this by allowing the plugin to add citations and export BibTeX files, effectively modifying the user's library contents.

Interactive Capability

The Interactive capability launches multi-step flows that require user confirmation or back-and-forth conversation before executing read or write operations. This is essential for workflows where the plugin needs clarification, such as confirming whether to import a specific reference into a Zotero library.

When combined with Read and Write, this capability supports complex workflows like searching email for invoices and then adding line items to QuickBooks only after explicit user approval.

How Data Access Is Controlled

Beyond the capabilities array, the .agents/plugins/marketplace.json file serves as the central registry that defines when and how data permissions are granted. Each plugin entry includes a policy dictionary that specifies the authentication mode, such as authentication: "ON_INSTALL".

This policy determines when the user must grant the plugin permission to read or write data. No plugin can arbitrarily access the host environment or other plugins' data unless they explicitly expose an API and the manifest declares the appropriate capability.

Code Examples: Accessing Data in Practice

The following examples demonstrate how different capabilities enable specific data access patterns using the OpenAI plugin system.

Reading User Data with the Read Capability

import openai

response = openai.ChatCompletion.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "@Zotero find papers in my library about transformers"}
    ],
    plugins=["zotero"]
)
print(response.choices[0].message.content)

The plugin reads the user's Zotero library via its API and returns matching items.

Writing Data with the Write Capability

response = openai.ChatCompletion.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "@Zotero add citation for key @smith2023 to my draft"}
    ],
    plugins=["zotero"]
)
print(response.choices[0].message.content)

The Write capability lets the plugin insert a citation key into the user's document.

Interactive Confirmation Flows

response = openai.ChatCompletion.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "@Zotero import this reference?"},
        {"role": "assistant", "content": "Sure, I'll add it to your Zotero library. Confirm? (yes/no)"}
    ],
    plugins=["zotero"]
)

The interactive capability ensures the user authorizes the write operation before the plugin modifies any data.

Combined Read, Write, and Interactive Operations

response = openai.ChatCompletion.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Summarize the last 3 invoices in my email, then add a line item to QuickBooks for each total."}
    ],
    plugins=["gmail", "quickbooks"]
)
print(response.choices[0].message.content)

The model reads email data via the Read capability of Gmail, then writes to QuickBooks via the Write capability, asking for confirmation when needed through the Interactive capability.

Key Files in the openai/plugins Repository

Understanding what data an OpenAI plugin can access requires examining these specific files:

• plugins/zotero/.codex-plugin/plugin.json: Defines the interface description and capabilities array (Read, Write, Interactive) that determine data access permissions.
• .agents/plugins/marketplace.json: Central registry containing each plugin's policy dictionary, which governs authentication timing and permission scopes.
• .agents/plugins/api_marketplace.json: Variant for API-key-authenticated users; applies the same capability rules with a different installation flow.

Summary

• OpenAI plugins access data through three capabilities: Read (retrieval), Write (modification), and Interactive (user confirmation).
• Access is restricted to declared scopes: The .codex-plugin/plugin.json manifest explicitly lists what operations the plugin can perform on external APIs.
• User authorization controls activation: The .agents/plugins/marketplace.json policy determines when authentication is required, typically at installation.
• Isolation prevents cross-plugin access: No plugin can read other plugins' data or the host environment without explicit API exposure and manifest declaration.

Frequently Asked Questions

Can an OpenAI plugin access data from other plugins?

No. According to the source code in the openai/plugins repository, plugins operate in isolated contexts. A plugin cannot arbitrarily read the host environment or access data from other plugins unless those plugins explicitly expose an API and the requesting plugin's manifest declares the appropriate capability to interface with that specific service.

What file defines what data a plugin can access?

The data access permissions are defined in the .codex-plugin/plugin.json manifest file within each plugin directory. For example, plugins/zotero/.codex-plugin/plugin.json specifies the capabilities (Read, Write, Interactive) that determine whether the plugin can retrieve, modify, or request confirmation before handling user data.

How does user authentication affect data access?

The .agents/plugins/marketplace.json file contains a policy dictionary for each plugin (e.g., authentication: "ON_INSTALL") that governs when users must grant data access permissions. A plugin can only access data after the user has authenticated and authorized the specific scopes requested in the manifest, ensuring no unauthorized data retrieval occurs.

Can a plugin modify data without user confirmation?

Only if the Interactive capability is not required. Plugins with Write capability alone can modify data directly, but best practices and specific implementations (like the Zotero example) often combine Write with Interactive to require user confirmation before creating, updating, or deleting resources. The manifest configuration determines whether confirmation flows are mandatory.

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