# How the OpenAI Plugins Marketplace Is Configured: A Technical Guide

> Discover how the OpenAI plugins marketplace is configured using the central marketplace.json manifest. Explore API endpoints, discovery paths, and authentication settings in this technical guide.

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

---

**The OpenAI plugins marketplace is configured through a central JSON manifest located at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), which defines the marketplace ID, API endpoints, plugin discovery paths, and authentication settings.**

The `openai/plugins` repository serves as the canonical source for the Codex and OpenAI plugin ecosystem. Understanding how the **marketplace is configured** centers on a declarative configuration system that automatically registers plugins and exposes them through unified APIs without requiring manual registration code.

## The Central marketplace.json Configuration File

At the root of the repository, the file [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) acts as the single source of truth for marketplace behavior. This JSON manifest supplies the core runtime parameters that power the plugin discovery system.

The marketplace loader reads this manifest on initialization to establish the foundational environment. According to the source structure, this file contains the essential metadata required to bootstrap the marketplace instance and configure how the system discovers and serves individual plugins.

## Key Marketplace Configuration Settings

The manifest defines several critical configuration keys that control marketplace operations:

### marketplaceId and apiBaseUrl

The **`marketplaceId`** field provides a unique identifier for the marketplace instance, enabling distinction between different deployment environments. The **`apiBaseUrl`** setting establishes the root path for all marketplace API calls, typically configured as `/api/marketplace` or similar endpoint prefixes.

### pluginDirectory and Discovery Paths

The **`pluginDirectory`** field specifies the relative path where the system scans for individual plugin definitions. By default, the loader searches the `plugins/` folder for valid descriptor files. The configuration supports multiple plugin definition formats, primarily looking for [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) files within plugin subdirectories or alternatively [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) for Codex-specific implementations.

### Authentication and Routing

The **`auth`** section contains optional authentication parameters, including API key requirements or OAuth scope definitions. The **`routingMap`** defines the URL mapping structure that connects marketplace routes to specific plugin handlers, while the **`metadata`** block stores human-readable information such as the marketplace name, description, and version string.

## How Plugin Discovery Works

When the repository initializes, the marketplace loader processes the manifest and automatically registers every valid plugin found under the configured directory. Each plugin must contain a descriptor file—either `plugins/<plugin-name>/.app.json` or `plugins/<plugin-name>/.codex-plugin/plugin.json`—that the loader validates against the marketplace schema.

This declarative approach enables **automatic plugin inclusion** without additional registration code. Developers simply add a valid JSON descriptor to the appropriate subdirectory, and the marketplace configuration handles the rest, exposing the plugin through GraphQL and REST APIs for consumption by Codex, Claude, and other LLM clients.

## Programmatic Access to Marketplace Configuration

You can programmatically inspect the marketplace configuration by fetching and parsing the manifest directly:

```python
import json
import urllib.request

# Load the marketplace manifest from the repository

url = "https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/marketplace.json"
with urllib.request.urlopen(url) as resp:
    marketplace = json.load(resp)

# Access core configuration values

api_base = marketplace["apiBaseUrl"]
marketplace_id = marketplace["marketplaceId"]

print(f"Marketplace ID: {marketplace_id}")
print(f"API Base URL: {api_base}")

# Construct endpoint for plugin listing

plugins_endpoint = f"{api_base}/plugins"

```

This pattern allows client applications to dynamically adapt to marketplace specifications without hardcoding endpoint values.

## Summary

- The **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)** file serves as the central configuration manifest for the entire OpenAI plugins marketplace.
- Key settings include **`marketplaceId`** for unique identification, **`apiBaseUrl`** for endpoint routing, and **`pluginDirectory`** for discovery paths.
- Plugins are automatically discovered through **`plugins/*/.app.json`** or **`plugins/*/.codex-plugin/plugin.json`** descriptors.
- The configuration supports optional **`auth`** parameters and a **`routingMap`** for handler mapping.
- No manual registration code is required; the marketplace loader processes the manifest and registers plugins automatically.

## Frequently Asked Questions

### What file format does the OpenAI plugins marketplace use for configuration?

The marketplace uses a JSON-based manifest system. The primary configuration resides in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), while individual plugin definitions use [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) or [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) formats within their respective plugin directories.

### Where does the marketplace look for plugin definitions?

According to the source configuration, the marketplace scans the relative path specified by the **`pluginDirectory`** setting (typically `plugins/`) for descriptor files. It searches for [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) files directly in plugin subdirectories or [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) files within `.codex-plugin/` subfolders.

### Can the marketplace configuration include authentication requirements?

Yes. The manifest supports an optional **`auth`** field that can specify API keys, OAuth scopes, or other security parameters. This allows the marketplace to enforce authentication standards across all registered plugins or specific plugin categories.

### How do I add a new plugin to the OpenAI marketplace?

Create a new subdirectory under `plugins/` and add a valid [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) descriptor file containing your plugin's metadata, endpoints, and schema definitions. The marketplace loader automatically discovers and registers the plugin on the next initialization cycle without requiring changes to the core marketplace configuration.