How to Specify Authentication Methods in an OpenAI Plugin Manifest

OpenAI plugins declare authentication requirements in the auth object of the .app.json manifest file, supporting three strategies: none for public data, service_http for OAuth 2.0 flows, and user_http for bearer tokens.

OpenAI plugins enable ChatGPT to interact with external APIs through a declarative JSON manifest. To establish secure connections with third-party services, developers must specify authentication methods in the .app.json file located in the repository root. This guide explains the three supported authentication strategies as implemented in the openai/plugins repository.

The Plugin Manifest Structure

The .app.json Configuration File

Each plugin is defined by a manifest file (conventionally named .app.json) that tells the ChatGPT platform how to load and invoke the plugin. According to the specification in .agents/skills/plugin-creator/references/plugin-json-spec.md, the auth object at the top level declares the credential flow required from users.

Supported Authentication Types

No Authentication (type: "none")

Use this type when the plugin accesses public data sources that require no credentials. The auth object requires only the type field set to "none".

Example from plugins/binance/.app.json:

{
  "apps": {
    "binance": {
      "id": "connector_abcdef123456"
    }
  },
  "auth": {
    "type": "none"
  }
}

Service HTTP OAuth 2.0 (type: "service_http")

This strategy implements OAuth 2.0 flows where users authorize the plugin by visiting an external service. As seen in plugins/google-drive/.app.json, this requires:

• authorization_url: The URL for user consent
• client_url: Optional documentation URL shown after authentication
• scope: Space-separated OAuth scopes

Example from the Google Drive plugin:

{
  "apps": {
    "google-drive": {
      "id": "connector_7b8c9d1e2f3g4h5i6j7k"
    }
  },
  "auth": {
    "type": "service_http",
    "authorization_url": "https://accounts.google.com/o/oauth2/auth?client_id=YOUR_CLIENT_ID&response_type=code&scope=https://www.googleapis.com/auth/drive.readonly",
    "client_url": "https://developers.google.com/drive/api/v3/about-auth",
    "scope": "https://www.googleapis.com/auth/drive.readonly"
  }
}

User HTTP Bearer Token (type: "user_http")

For simple API key authentication where users supply tokens directly, use this type. The manifest optionally includes:

• authorization_url: Page where users obtain tokens
• client_url: Help documentation
• scope: Description of token permissions

Implementation Guide

1. Locate your plugin's .app.json file in the repository (e.g., plugins/gmail/.app.json).
2. Add the auth object at the top level, alongside the apps section.
3. Set the type field to "none", "service_http", or "user_http".
4. Populate OAuth URLs and scopes for service-based authentication, or leave minimal for public access.

Key Reference Files

File	Purpose
plugins/google-drive/.app.json	Complete OAuth 2.0 implementation with service_http type
plugins/gmail/.app.json	Email service OAuth 2.0 configuration
plugins/binance/.app.json	Minimal none authentication for public market data
.agents/skills/plugin-creator/references/plugin-json-spec.md	Official schema documentation defining allowed auth fields

Summary

• The .app.json manifest requires an auth object to specify how ChatGPT authenticates with your plugin.
• Three authentication strategies are supported: none for public APIs, service_http for OAuth 2.0, and user_http for bearer tokens.
• OAuth implementations require authorization_url and scope fields, while public plugins need only type: "none".
• Reference implementations exist in the openai/plugins repository for Google Drive, Gmail, and Binance.

Frequently Asked Questions

What happens if I don't include an auth object in my plugin manifest?

The ChatGPT platform requires the auth field to determine the credential flow. Omitting it causes validation errors during plugin installation. Always include at least {"type": "none"} for public data sources.

Can I use multiple authentication types in the same plugin?

No, each plugin manifest supports exactly one authentication strategy in the auth object. If your service supports both OAuth and API keys, create separate plugin configurations or choose the most secure method supported by your use case.

Where do users obtain OAuth client credentials for service_http plugins?

Users authorize through the authorization_url you specify, which redirects to the external service (e.g., Google Accounts). The plugin receives the OAuth token after consent, not the client ID/secret, which remain secure on your backend.

Is the user_http type compatible with API keys that use custom headers?

The user_http type typically expects bearer tokens in the Authorization header. For custom header requirements, implement the authentication logic in your API backend to translate the standard bearer token into your service's required format.

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