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

The .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, contains the unique identifier that the platform uses to route requests and verify plugin authenticity during runtime operations.

Core Purpose of the .app.json File

The .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, it performs three essential functions that bridge local development with platform deployment.

App Identification and Routing

The primary responsibility of .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:

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

Manifest Generation Bridge

During the build process, tooling reads .app.json to inject the correct app_id into the final 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 schema is intentionally minimal, containing only a nested apps object where keys represent plugin names and values contain the connector metadata.

{
  "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

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

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

# 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 file works in concert with other configuration files in the openai/plugins repository structure:

• ai-plugin.json – The public-facing manifest that consumes the app_id from .app.json during the build process. While .app.json remains in the repository for development, ai-plugin.json is what the OpenAI platform actually reads to discover plugin capabilities.

• .codex-plugin/plugin.json – Contains internal Codex-specific metadata that describes AI capabilities, complementing the connector information stored in .app.json.

• README.md – Provides human-readable documentation that often references the app ID for debugging or setup instructions.

Summary

• The .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 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 file is missing from a plugin directory?

Without the .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 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 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 file affect local plugin development?

During local development, the .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 manifests contain the correct identifiers for testing against OpenAI's sandbox environments.

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