# How to Define the Scope and Permissions for Your OpenAI Plugin

> Define OpenAI plugin scope and permissions by configuring the auth.scopes array and permissions field in your plugin.json manifest file. Learn how to set access control.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-07-05

---

**You define the scope and permissions for your OpenAI plugin by configuring the `auth.scopes` array and optional `permissions` field in the [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`:

```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:

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

### What is the difference between `auth.scopes` and `permissions` in [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.