# How to Integrate with OpenAI's API Using a Plugin: Complete Implementation Guide

> Master OpenAI API integration with plugins. This guide reveals how to use the openai-developers plugin for seamless API key management and error recovery, empowering your custom skills.

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

---

**You integrate with OpenAI's API using a plugin by leveraging the `openai-developers` plugin as a credential gate, which automatically provisions API keys and handles error recovery before your custom skills execute HTTP calls to `https://api.openai.com/v1/*`.**

The **openai/plugins** repository provides a declarative framework for building Codex plugins that connect to external services. Instead of writing boilerplate authentication logic, you compose **skills**—markdown-driven actions defined by YAML agents—that reuse the `openai-platform-api-key` and `openai-api-troubleshooting` utilities to securely manage API access.

## Understanding the Plugin Architecture

Every plugin in the repository follows a strict directory layout that separates configuration from implementation.

**Plugin Manifest** (`plugins/<plugin-name>/.codex-plugin/plugin.json`): Declares the plugin metadata, version, and skill directory path. This is the entry point Codex reads to load your plugin.

**App Manifest** (`plugins/<plugin-name>/.app.json`): Defines the bridge to the OpenAI Platform, including authentication flows and endpoint configurations.

**Skills** (`plugins/<plugin-name>/skills/<skill-name>/`): Contain the actual functionality. Each skill includes:
- [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md): Markdown documentation describing inputs, outputs, and behavior.
- [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml): Configuration specifying the model, temperature, and tools (including HTTP endpoints).

**Agents** ([`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml)): These YAML files instruct Codex how to invoke the skill. They reference environment variables like `{{ env.OPENAI_API_KEY }}` and define HTTP tools for POST requests to the OpenAI API.

## The OpenAI Developers Plugin

The `plugins/openai-developers` directory houses two critical skills that form a **credential gate** for any integration:

**`openai-platform-api-key`**: As implemented in [`plugins/openai-developers/skills/openai-platform-api-key/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/skills/openai-platform-api-key/SKILL.md), this skill checks for an existing `OPENAI_API_KEY` environment variable. If missing, it prompts the user through the OpenAI Platform picker and writes the key to a local `.env` file.

**`openai-api-troubleshooting`**: Located at [`plugins/openai-developers/skills/openai-api-troubleshooting/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/skills/openai-api-troubleshooting/SKILL.md), this skill intercepts API failures (401 authentication errors, quota limits, or network blocks) and routes users to appropriate remediation flows.

When you build a plugin that calls OpenAI endpoints, you declare a dependency on these skills rather than handling credentials manually.

## Implementing Your OpenAI API Integration

Follow these steps to create a new plugin that securely calls the OpenAI API.

### Scaffolding a New Plugin

Use the provided helper script to generate the correct directory structure:

```bash
python .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    --name my-openai-assistant \
    --description "A simple chat assistant powered by the OpenAI API"

```

This creates the standard layout including [`plugins/my-openai-assistant/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/my-openai-assistant/.codex-plugin/plugin.json) and the `skills/` directory.

### Configuring the Plugin Manifest

Edit the generated [`plugins/my-openai-assistant/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/my-openai-assistant/.codex-plugin/plugin.json) to declare your plugin metadata:

```json
{
  "name": "my-openai-assistant",
  "version": "0.1.0",
  "description": "A simple chat assistant powered by the OpenAI API",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/yourname"
  },
  "skills": "./skills/",
  "interface": {
    "displayName": "My OpenAI Assistant",
    "shortDescription": "Chat with GPT-4 in a custom UI",
    "brandColor": "#3B82F6",
    "composerIcon": "./assets/icon.png"
  }
}

```

### Defining the Agent and Skills

Create the skill directory structure at `plugins/my-openai-assistant/skills/chat/` and add the agent configuration in [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml):

```yaml
model: gpt-4
temperature: 0.7
tools:
  - name: openai_chat
    type: http
    method: POST
    url: https://api.openai.com/v1/chat/completions
    headers:
      Authorization: "Bearer {{ env.OPENAI_API_KEY }}"
    body:
      model: gpt-4
      messages: "{{ messages }}"

```

Then document the skill in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md):

```markdown

# Chat with GPT-4

Use this skill to send a list of messages to `chat/completions` and receive the model's reply.

## Input

- `messages` – an array of `{role, content}` objects.

## Output

- The `assistant` message returned by the API.

```

Place any UI assets (icons, logos) in `plugins/my-openai-assistant/assets/` to ensure marketplace compatibility.

## How the Credential Flow Works

When a user invokes your plugin, the execution follows this sequence:

1. **Invocation**: ChatGPT loads your plugin and reads the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest.
2. **Credential Check**: The `openai-platform-api-key` skill verifies `OPENAI_API_KEY` exists. If absent, it executes the provisioning flow before your skill runs.
3. **API Execution**: Your agent makes the HTTP POST to `https://api.openai.com/v1/chat/completions` using the stored key.
4. **Error Handling**: If the API returns a 401 or 429 error, the `openai-api-troubleshooting` skill parses the response, distinguishes between authentication and quota issues, and either retries or redirects to the credential gate.

This declarative approach means you can add new OpenAI endpoints (embeddings, fine-tuning, or image generation) by writing new [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files and updating the [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) tools array, without modifying the underlying authentication infrastructure.

## Summary

- **Reuse the credential gate**: Always depend on `plugins/openai-developers` skills to handle `OPENAI_API_KEY` provisioning rather than implementing custom key management.
- **Follow the manifest structure**: Place your configuration in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) to ensure Codex recognizes your plugin.
- **Define agents in YAML**: Use [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) to declare HTTP tools that reference `{{ env.OPENAI_API_KEY }}` for secure API calls.
- **Document in markdown**: Write [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files to describe inputs and outputs, making your skills discoverable and maintainable.
- **Use scaffolding tools**: Run [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) from `.agents/skills/plugin-creator/scripts/` to ensure correct file layouts.

## Frequently Asked Questions

### What is the purpose of the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file?

The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file serves as the entry point that Codex reads to load your plugin. It declares the plugin name, version, author information, and the path to the skills directory, as specified in the repository's plugin JSON specification.

### How does the OpenAI Developers plugin handle API key security?

The `openai-platform-api-key` skill securely creates or reuses an `OPENAI_API_KEY` and writes it to a local `.env` file. It prompts the user about existing keys and stores them safely, ensuring downstream skills never handle raw credentials in code.

### Can I integrate with OpenAI endpoints other than chat completions?

Yes. You can integrate with any OpenAI endpoint (embeddings, fine-tuning, image generation) by creating a new skill with a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) description and an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) that defines an HTTP tool pointing to the specific endpoint URL, such as `https://api.openai.com/v1/embeddings`.

### What happens when an API call fails?

The `openai-api-troubleshooting` skill detects common failure modes including network blocks, invalid keys, and quota limits. It parses the error response and routes the user to the appropriate remediation flow, either retrying with escalated permissions or redirecting to the credential gate for key regeneration.