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

> Discover the purpose of the .app.json file in OpenAI plugins. This manifest file maps plugins to their ChatGPT App connectors, streamlining request routing and authentication.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: architecture
- Published: 2026-06-30

---

**The [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/slack/.app.json), the configuration appears as:

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

```

Similarly, [`plugins/zoom/.app.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.app.json) follows the same pattern:

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

```

## How .app.json Connects Plugins to ChatGPT Apps

The primary purpose of [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). This file references [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) through the `apps` key, directing the platform to load the app ID from the separate configuration file.

A typical [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) excerpt shows this relationship:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/README.md) in the repository root explicitly lists [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json) configuration to initialize the appropriate connector. The following pseudo-code illustrates how the Codex runtime might consume this file:

```python

# 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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) references [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/slack/.app.json) and [`plugins/zoom/.app.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json) file resides in the root directory of each plugin. For example, you can find it at [`plugins/slack/.app.json`](https://github.com/openai/plugins/blob/main/plugins/slack/.app.json) and [`plugins/zoom/.app.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) includes an `apps` key that points to the [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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.