Purpose of the .app.json File in OpenAI Plugins: Configuration and App Mapping

The .app.json file acts as a manifest that maps each plugin to its corresponding ChatGPT App connector, enabling the runtime to route requests and handle authentication for third-party services.

The openai/plugins repository contains reference implementations for extending ChatGPT capabilities through plugins. At the heart of every plugin directory lies the .app.json file, a critical configuration manifest that bridges static plugin code with the dynamic ChatGPT App infrastructure. This file centralizes the app identifier, making plugins portable and allowing the platform to manage authentication, rate-limiting, and permission scopes without hard-coding values in the plugin source.

What Is the .app.json File?

The .app.json file is a JSON manifest located in the root of each plugin directory. It declares which ChatGPT App connector provides the underlying API integration for that specific plugin.

According to the repository structure documented in README.md, this file is a required surface for all plugins. The file contains a top-level apps object where keys represent the plugin's logical name (e.g., slack, zoom) and values contain the id of the corresponding ChatGPT app.

For example, in plugins/slack/.app.json, the configuration appears as:

{
  "apps": {
    "slack": {
      "id": "asdk_app_69a1d78e929881919bba0dbda1f6436d"
    }
  }
}

Similarly, plugins/zoom/.app.json follows the same pattern:

{
  "apps": {
    "zoom": {
      "id": "asdk_app_69373a13116c819189d046aea1278836"
    }
  }
}

How .app.json Connects Plugins to ChatGPT Apps

The primary purpose of .app.json is mapping a plugin to an app. The id field contains the unique identifier for the ChatGPT App connector (prefixed with asdk_app_*), which handles the actual OAuth flows, token refresh, and API communication with the third-party service.

When a user invokes a plugin action (e.g., "post a message to Slack"), the Codex/ChatGPT runtime performs the following steps:

1. Loads the plugin's .app.json file
2. Extracts the id from the apps object using the plugin name
3. Establishes a connection to the corresponding ChatGPT App connector
4. Forwards the request with proper OAuth credentials and permission scopes

This abstraction allows the plugin code to remain agnostic of specific authentication tokens while the runtime manages secure communication through the designated app connector.

Integration with the Plugin Manifest

Every plugin contains a main manifest file located at .codex-plugin/plugin.json. This file references .app.json through the apps key, directing the platform to load the app ID from the separate configuration file.

A typical plugin.json excerpt shows this relationship:

{
  "name": "Zoom",
  "description": "Interact with Zoom meetings",
  "apps": "./.app.json",
  "commands": "./commands",
  "agents": "./agents"
}

This indirection provides flexibility—developers can update app IDs or switch between development and production app connectors without modifying the main plugin manifest. The README.md in the repository root explicitly lists .app.json as one of the required surfaces that enables this "app-backed" architecture.

Runtime Authentication and Routing

At runtime, the platform uses the .app.json configuration to initialize the appropriate connector. The following pseudo-code illustrates how the Codex runtime might consume this file:

# Codex runtime (simplified)

with open('.app.json') as f:
    app_manifest = json.load(f)
    
app_id = app_manifest['apps'][plugin_name]['id']
client = ChatGPTAppConnector(app_id)   # handles OAuth, token refresh, etc.

response = client.call('postMessage', payload)

Because the .app.json file isolates the app identifier from the plugin logic, the same plugin code can operate against different app connectors (such as staging versus production environments) by simply swapping the configuration file. This portability is essential for the "app-backed" nature of the OpenAI plugins ecosystem.

Summary

• .app.json is a required manifest in every plugin directory that declares the ChatGPT App connector ID for that plugin.
• The file contains an apps object mapping plugin names to asdk_app_* identifiers, enabling the runtime to locate the correct connector.
• The plugin manifest at .codex-plugin/plugin.json references .app.json via the "apps": "./.app.json" entry.
• This configuration decouples authentication logic from plugin code, allowing the platform to manage OAuth, rate-limiting, and permissions through the designated app connector.
• Examples in plugins/slack/.app.json and plugins/zoom/.app.json demonstrate the consistent structure across all plugins in the repository.

Frequently Asked Questions

What format does the .app.json file use?

The .app.json file uses standard JSON format with a top-level apps object. Each key in this object represents the plugin's logical name, and the corresponding value is an object containing an id field with the ChatGPT App connector identifier (e.g., asdk_app_69a1d78e929881919bba0dbda1f6436d).

Where is the .app.json file located in a plugin directory?

The .app.json file resides in the root directory of each plugin. For example, you can find it at plugins/slack/.app.json and plugins/zoom/.app.json in the openai/plugins repository. This location is consistent across all plugins to ensure the platform can discover the configuration automatically.

How does the plugin manifest reference the .app.json file?

The main plugin manifest located at .codex-plugin/plugin.json includes an apps key that points to the .app.json file using a relative path: "apps": "./.app.json". This reference tells the Codex/ChatGPT runtime where to find the app connector mapping when loading the plugin.

Why is the app ID important for plugin functionality?

The app ID (stored in the id field of .app.json) is crucial because it tells the runtime which ChatGPT App connector to instantiate for handling requests. This connector manages all OAuth authentication, token refresh, and API communication with the third-party service (such as Slack or Zoom), allowing the plugin to execute actions without embedding sensitive credentials in its code.

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