How to Define the Scope and Permissions for Your OpenAI Plugin

You define the scope and permissions for your OpenAI plugin by configuring the auth.scopes array and optional permissions field in the plugin.json manifest file located in your plugin's .codex‑plugin directory.

To control what data your plugin can access, you must properly define the scope and permissions in the manifest configuration. The openai/plugins repository uses the plugin.json file to declare OAuth requirements and fine-grained access controls that the platform presents to users during installation.

Locating the Plugin Manifest

Every plugin stores its configuration in a .codex‑plugin directory within its folder. The manifest file at plugins/<plugin-name>/.codex‑plugin/plugin.json declares authentication requirements and permissions.

For example, the Airtable plugin manifest lives at: plugins/airtable/.codex‑plugin/plugin.json

Configuring OAuth Scopes

To request user-level access to external APIs, set auth.type to "oauth" and define the required scopes in the auth.scopes array.

Required Authentication Fields

• auth.type: Must be "oauth" for plugins requiring user-level access.
• auth.scopes: An array of OAuth scope strings representing the minimum permissions required to call the external API.
• auth.redirect_uri: Optional URL to which the OAuth provider redirects after authorization.

Fine-Grained Permissions

The optional top-level permissions array documents granular access levels separate from OAuth scopes. Some services expose permissions distinct from OAuth scopes; list these here for UI rendering and documentation purposes.

Step-by-Step Implementation

1. Open your plugin's manifest at .codex‑plugin/plugin.json (e.g., plugins/airtable/.codex‑plugin/plugin.json).
2. Add the auth object with type: "oauth".
3. Populate auth.scopes with only the permissions you truly need—follow the principle of least privilege.
4. Optionally add permissions array for documentation of granular access levels.
5. Commit the manifest—the OpenAI platform reads these fields during installation and OAuth flow initiation.

Complete Configuration Example

Reference the Airtable plugin implementation in plugins/airtable/.codex‑plugin/plugin.json:

{
  "name": "airtable",
  "description": "Access Airtable bases and records",
  "auth": {
    "type": "oauth",
    "scopes": [
      "data.records:read",
      "data.records:write"
    ],
    "redirect_uri": "https://myplugin.com/oauth/callback"
  },
  "permissions": [
    "read_base",
    "write_record"
  ],
  "api": {
    "base_url": "https://api.airtable.com/v0"
  }
}

The Zoom plugin at plugins/zoom/.codex‑plugin/plugin.json demonstrates how different services structure their scope declarations.

Runtime Scope Verification

Verify granted scopes before calling external APIs to ensure the user authorized the required permissions. The following Node.js implementation checks token payloads against required scopes:

function hasRequiredScopes(tokenPayload, requiredScopes) {
  const tokenScopes = tokenPayload.scope.split(' ');
  return requiredScopes.every(s => tokenScopes.includes(s));
}

// Example usage
if (!hasRequiredScopes(decodedJwt, ['data.records:write'])) {
  throw new Error('Missing required write scope for Airtable');
}

Managing Scope Updates

When you modify auth.scopes in plugin.json, existing user tokens do not automatically inherit new permissions. Users must re‑authorize the plugin to grant the additional access.

After committing scope changes, prompt users with a message indicating that the plugin’s required scopes have been updated and they must reinstall or click "Re‑authorize" in the OpenAI UI for the changes to take effect.

Summary

• Define OAuth scopes in the auth.scopes array within plugin.json.
• Set auth.type to "oauth" to enable user-level authentication.
• Use the optional permissions array for documenting fine-grained access levels.
• Reference plugins/airtable/.codex‑plugin/plugin.json and plugins/zoom/.codex‑plugin/plugin.json for implementation examples.
• Verify scopes at runtime before making external API calls.
• Users must re-authorize the plugin after any scope changes.

Frequently Asked Questions

Where do I declare OAuth scopes for my OpenAI plugin?

Declare OAuth scopes in the auth.scopes array within your plugin.json manifest file, located in the .codex‑plugin directory of your plugin. Set auth.type to "oauth" to enable the OAuth flow, as specified in the repository's root README.md.

What is the difference between auth.scopes and permissions in plugin.json?

The auth.scopes array defines OAuth scopes requested during the authorization flow, while the optional permissions array documents fine-grained access levels for UI rendering and documentation. Some services distinguish between OAuth scopes and granular permissions, so both fields can coexist in the manifest.

Do users need to reinstall the plugin when I add new scopes?

Yes, users must re-authorize the plugin when you add or change scopes in plugin.json. Tokens issued before the change will not automatically acquire the new scopes, and the platform requires fresh consent for the updated permissions.

How do I verify that a user has granted the required scopes at runtime?

Inspect the token payload (usually a JWT) and check that the scope claim contains all required permissions. Implement a validation function that splits the scope string and verifies every required scope is present before calling external APIs.

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