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

> Learn how to use .app.json to map your plugin to a ChatGPT connector ID for automatic authentication and API routing. Simplify app-backed plugins like Figma and Notion.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-07-04

---

**The [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json)?

The [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json) file in your plugin's root directory. For example, the Figma plugin stores its manifest at [`plugins/figma/.app.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.app.json), while Notion uses [`plugins/notion/.app.json`](https://github.com/openai/plugins/blob/main/plugins/notion/.app.json).

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

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

```

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

```

## Linking the Manifest in plugin.json

To activate the app dependency, reference the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file in your plugin manifest. According to the plugin-creator spec at [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md), add the `apps` field pointing to your manifest:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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:

```javascript
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`](https://github.com/openai/plugins/blob/main/plugins/figma/README.md) and [`plugins/notion/README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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.