How to Use .app.json for App-Backed Plugins Like Figma and Notion

The .app.json file acts as an app-dependency manifest that maps your plugin to a ChatGPT connector ID, enabling automatic authentication and API routing without embedding credentials in your skill code.

The openai/plugins repository supports app-backed plugins that integrate with external services like Figma and Notion through a special configuration file. By creating a .app.json file in your plugin root, you establish a secure bridge between your Codex skills and ChatGPT's App Store connectors, allowing the platform to handle OAuth and API calls automatically.

What Is .app.json?

The .app.json file is the app-dependency manifest that tells the Codex platform which ChatGPT app (connector) your plugin should use. Unlike traditional plugins that require manual API key management, app-backed plugins store only the connector identifier in source control, while the platform injects user authentication tokens at runtime.

File Location and Structure

Place the .app.json file in your plugin's root directory. For example, the Figma plugin stores its manifest at plugins/figma/.app.json, while Notion uses plugins/notion/.app.json.

Each file maps an app name to its unique connector ID:

{
  "apps": {
    "figma": {
      "id": "connector_68df038e0ba48191908c8434991bbac2"
    }
  }
}

{
  "apps": {
    "notion": {
      "id": "asdk_app_69c18c28f1188191bf5b8445c4ab0a2e"
    }
  }
}

Linking the Manifest in plugin.json

To activate the app dependency, reference the .app.json file in your plugin manifest. According to the plugin-creator spec at .agents/skills/plugin-creator/references/plugin-json-spec.md, add the apps field pointing to your manifest:

{
  "name": "figma",
  "version": "0.1.0",
  "description": "Figma-backed design-to-code plugin",
  "apps": "./.app.json",
  "skills": ["figma-implement-design", "figma-generate-design"]
}

How the Platform Resolves App Connections

When a user invokes your plugin, Codex performs a multi-step resolution process to authenticate and route requests.

Runtime Authentication Flow

1. Codex reads the connector ID from .app.json.
2. The platform matches this ID against the user's linked apps in their ChatGPT UI.
3. All skill-level API calls route through the connected app with injected OAuth tokens.
4. Your skill code never handles raw credentials.

Single Source of Truth

Because the connector ID lives only in .app.json, you maintain a single configuration point. This architecture enables zero-code integration—skills don't embed app credentials, and the same plugin works across different user accounts without modification.

Accessing App IDs in Skill Code

While the platform handles authentication automatically, you can access the connector ID programmatically when needed. This Node.js example loads the manifest from a skill directory:

const fs = require('fs');
const path = require('path');

// Load the app manifest (relative to the skill folder)
const appManifest = JSON.parse(
  fs.readFileSync(path.join(__dirname, '..', '..', '.app.json'), 'utf8')
);

const figmaAppId = appManifest.apps.figma.id;
// => "connector_68df038e0ba48191908c8434991bbac2"

The skill code never accesses the user's OAuth token directly. Codex injects the token after matching the app ID with the user's linked Figma app, as documented in the plugins/figma/README.md and plugins/notion/README.md files.

Creating a New App-Backed Plugin

To add a new app-backed integration:

1. Create a folder at plugins/<your-app>/.
2. Add a .app.json file containing the connector ID from the ChatGPT App Store.
3. Reference it in your plugin manifest using "apps": "./.app.json".
4. Write skills normally; they automatically call the connected app through the platform.

Summary

• The .app.json file serves as the app-dependency manifest for OpenAI Codex plugins.
• Store connector IDs in plugins/<app>/.app.json to map your plugin to ChatGPT apps.
• Reference the manifest in plugin.json using the apps field.
• The platform handles authentication automatically, injecting tokens at runtime without exposing credentials in your code.
• This architecture provides a single source of truth and enables portable, zero-code integrations with services like Figma and Notion.

Frequently Asked Questions

Where do I find the connector ID for my app?

You obtain the connector ID from the ChatGPT App Store when registering your app. The ID (such as connector_68df038e0ba48191908c8434991bbac2 for Figma) uniquely identifies your app in the Codex platform and remains constant across all plugin installations.

Can I use multiple app connectors in one plugin?

Yes. The .app.json structure supports multiple apps under the apps object. Each app maps to its own connector ID, and you can reference them individually in your skills while the platform manages authentication for each service separately.

Do I need to handle OAuth tokens in my skill code?

No. The primary advantage of using .app.json is that Codex handles OAuth authentication internally. Your skills make API calls through the platform, which injects the appropriate user tokens after resolving the connector ID, keeping your code free of credential management logic.

What happens if a user hasn't linked the app in ChatGPT?

If a user attempts to use your plugin without linking the corresponding app (such as Figma or Notion) in their ChatGPT UI, the platform will prompt them to authenticate or connect the app before proceeding with any skill invocations.

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