# OpenAI Plugin `.app.json` File: Purpose, Schema, and Implementation

> Discover the purpose and schema of the .app.json file in OpenAI plugins. Learn how it links your plugin to its backend app for authentication and manifest generation.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-09-12

---

**The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file stores the platform-generated connector ID that links an OpenAI plugin to its registered backend app, enabling authentication and manifest generation.**

The `openai/plugins` repository uses a hidden configuration file at the root of each plugin directory to maintain the critical link between plugin code and the OpenAI platform infrastructure. This file, named [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), contains the unique identifier that the platform uses to route requests and verify plugin authenticity during runtime operations.

## Core Purpose of the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) File

The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file serves as the authoritative source for **application-level metadata** required by the OpenAI plugin ecosystem. Located at paths like [`plugins/slack/.app.json`](https://github.com/openai/plugins/blob/main/plugins/slack/.app.json), it performs three essential functions that bridge local development with platform deployment.

### App Identification and Routing

The primary responsibility of [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) is to store the `app_id`—a unique identifier generated by the OpenAI platform when a connector is registered. According to the source code in the `openai/plugins` repository, this ID acts as the trusted key that backend services use to verify incoming requests originate from an authentic OpenAI-managed connector.

The file creates a deterministic mapping between the plugin's directory name and its platform identity. For example, the Slack plugin contains:

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

```

### Manifest Generation Bridge

During the build process, tooling reads [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) to inject the correct `app_id` into the final [`ai-plugin.json`](https://github.com/openai/plugins/blob/main/ai-plugin.json) manifest. This ensures the public plugin descriptor contains the accurate connector reference required for the OpenAI platform to establish secure communication channels with the plugin's API endpoints.

### CI/CD Validation

Because the file is checked into version control, continuous integration pipelines can verify that every plugin in the repository maintains a valid link to a registered app before marketplace publication. This prevents deployment of orphaned plugins that lack proper platform registration.

## File Structure and Schema

The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) schema is intentionally minimal, containing only a nested `apps` object where keys represent plugin names and values contain the connector metadata.

```json
{
  "apps": {
    "<plugin-name>": {
      "id": "<platform-generated-connector-id>"
    }
  }
}

```

The `id` value always follows the pattern `asdk_app_<hash>`, representing the unique platform identifier for the plugin's connector.

## Practical Implementation Examples

When developing tooling for the `openai/plugins` repository, you frequently need to extract the `app_id` programmatically for configuration generation or runtime verification.

### Reading `app_id` in Node.js

```javascript
import { readFileSync } from 'fs';
import path from 'path';

function getAppId(pluginDir) {
  const filePath = path.join(pluginDir, '.app.json');
  const data = JSON.parse(readFileSync(filePath, 'utf8'));
  const pluginName = Object.keys(data.apps)[0];
  return data.apps[pluginName].id;
}

// Usage
const slackAppId = getAppId('plugins/slack');
console.log('Slack app ID:', slackAppId);

```

### Reading `app_id` in Python

```python
import json
from pathlib import Path

def get_app_id(plugin_dir: Path) -> str:
    file = plugin_dir / ".app.json"
    with file.open() as f:
        data = json.load(f)
    plugin_name = next(iter(data["apps"]))
    return data["apps"][plugin_name]["id"]

# Example

slack_id = get_app_id(Path("plugins/slack"))
print(f"Slack app ID: {slack_id}")

```

### Manifest Generation in Build Scripts

```bash

# Extract ID and inject into ai-plugin.json

APP_ID=$(jq -r '.apps[].id' plugins/slack/.app.json)

cat > plugins/slack/ai-plugin.json <<EOF
{
  "schema_version": "v1",
  "name_for_human": "Slack",
  "name_for_model": "slack",
  "auth": {
    "type": "service_http",
    "app_id": "${APP_ID}"
  }
}
EOF

```

## Relationship to Other Plugin Files

The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file works in concert with other configuration files in the `openai/plugins` repository structure:

- **[`ai-plugin.json`](https://github.com/openai/plugins/blob/main/ai-plugin.json)** – The public-facing manifest that consumes the `app_id` from [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) during the build process. While [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) remains in the repository for development, [`ai-plugin.json`](https://github.com/openai/plugins/blob/main/ai-plugin.json) is what the OpenAI platform actually reads to discover plugin capabilities.

- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** – Contains internal Codex-specific metadata that describes AI capabilities, complementing the connector information stored in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json).

- **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)** – Provides human-readable documentation that often references the app ID for debugging or setup instructions.

## Summary

- The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file stores the **platform-generated connector ID** (`app_id`) that authenticates the plugin to the OpenAI infrastructure.
- Located at `plugins/<name>/.app.json`, it maps plugin directory names to unique identifiers like `asdk_app_69a1d78e929881919bba0dbda1f6436d`.
- Build systems reference this file to inject the correct `app_id` into [`ai-plugin.json`](https://github.com/openai/plugins/blob/main/ai-plugin.json) during manifest generation.
- Version-controlling this file ensures consistent, reproducible plugin registration across development, staging, and production environments.

## Frequently Asked Questions

### What happens if the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file is missing from a plugin directory?

Without the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file, the plugin lacks the verified connector ID required for the OpenAI platform to authenticate requests. CI pipelines in the `openai/plugins` repository typically fail validation when this file is absent, preventing deployment of a plugin that cannot establish secure communication with its backend.

### How is the `app_id` in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) different from the plugin name?

The plugin name (the key under `apps` in the JSON structure) is a human-readable identifier matching the directory name, while the `app_id` is a cryptographically secure, platform-generated string starting with `asdk_app_`. The OpenAI infrastructure uses this ID—not the friendly name—to route API calls and verify JWT tokens during request handling.

### Can the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file contain multiple app definitions?

While the schema supports multiple entries under the `apps` key, typical implementations in the `openai/plugins` repository contain a single mapping between the plugin directory name and its connector ID. This design maintains a strict 1:1 relationship between a plugin codebase and its registered platform connector.

### Does the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file affect local plugin development?

During local development, the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file primarily enables accurate manifest generation and validation. While the actual authentication checks against the `app_id` occur in the deployed environment, having this file locally ensures that generated [`ai-plugin.json`](https://github.com/openai/plugins/blob/main/ai-plugin.json) manifests contain the correct identifiers for testing against OpenAI's sandbox environments.