How to Add Privacy Policy and Terms of Service URLs to OpenAI Plugins

Add privacyPolicyURL and termsOfServiceURL fields to your plugin's .codex-plugin/plugin.json manifest file, ensuring both use valid HTTPS URLs.

The openai/plugins repository requires every plugin to define its legal and privacy disclosures through a standardized manifest file. To add privacy policy and terms of service URLs to OpenAI plugins, you must edit the JSON configuration located in each plugin's hidden .codex-plugin directory, following the Plugin JSON Specification used across all integrations including Zotero, Zoom, and Superhuman.

Understanding the Plugin Manifest Structure

Every plugin in the repository stores its configuration in plugins/<plugin-name>/.codex-plugin/plugin.json. This manifest follows the Plugin JSON Specification and supports two optional top-level string fields for legal compliance:

• privacyPolicyURL: HTTPS URL pointing to the provider's privacy policy
• termsOfServiceURL: HTTPS URL pointing to the terms of service or terms of use

The OpenAI system reads these fields during registration and displays the links on the plugin's detail page to end-users.

Real-world implementations in the repository demonstrate this pattern:

• Zotero: plugins/zotero/.codex-plugin/plugin.json
• Zoom: plugins/zoom/.codex-plugin/plugin.json
• Superhuman: plugins/superhuman/.codex-plugin/plugin.json

Step-by-Step Implementation

Locate the Manifest File

Navigate to your plugin's configuration directory:

plugins/<your-plugin>/.codex-plugin/plugin.json

Add the Required Fields

Insert privacyPolicyURL and termsOfServiceURL as top-level keys in the JSON object. These fields accept string values representing HTTPS endpoints:

{
  "name": "my-plugin",
  "description": "Brief description of the plugin.",
  "api": {
    "type": "openapi",
    "url": "https://my-plugin.com/openapi.yaml"
  },
  "auth": {
    "type": "none"
  },
  "privacyPolicyURL": "https://my-plugin.com/privacy",
  "termsOfServiceURL": "https://my-plugin.com/terms"
}

Validate and Commit

Ensure both URLs use the https:// protocol and are publicly accessible. Commit the updated plugin.json to the main branch. The repository includes validation scripts to check manifest schema compliance—run npm run lint to verify your changes before submitting.

Implementation Examples

Basic Plugin Without Authentication

For plugins using no authentication or API key-based auth, add the fields alongside your API configuration:

{
  "name": "quick-notes",
  "description": "Create and retrieve notes.",
  "api": {
    "type": "openapi",
    "url": "https://quick-notes.com/openapi.yaml"
  },
  "auth": { "type": "none" },
  "privacyPolicyURL": "https://quick-notes.com/privacy",
  "termsOfServiceURL": "https://quick-notes.com/terms"
}

OAuth-Protected Plugin

For OAuth integrations, place the legal URLs at the root level alongside your authorization configuration:

{
  "name": "task-manager",
  "description": "Interact with a task-management SaaS.",
  "api": {
    "type": "openapi",
    "url": "https://task-manager.com/openapi.yaml"
  },
  "auth": {
    "type": "oauth",
    "authorizationUrl": "https://task-manager.com/oauth/authorize",
    "tokenUrl": "https://task-manager.com/oauth/token",
    "scopes": ["tasks.read", "tasks.write"]
  },
  "privacyPolicyURL": "https://task-manager.com/privacy",
  "termsOfServiceURL": "https://task-manager.com/terms"
}

Updating an Existing Plugin

If your plugins/example/.codex-plugin/plugin.json lacks these fields, apply this diff:

{
   "name": "example",
   "description": "Demo plugin.",
   "api": {
     "type": "openapi",
     "url": "https://example.com/openapi.yaml"
   },
   "auth": { "type": "none" },
+  "privacyPolicyURL": "https://example.com/privacy",
+  "termsOfServiceURL": "https://example.com/terms"
 }

Compliance and Transparency Requirements

Adding these URLs serves three critical functions:

• Legal Compliance: Platforms hosting these plugins must surface privacy policies and terms of service to satisfy regulatory requirements and platform policies.
• User Transparency: End-users can review data-handling practices before authorizing plugin access, reducing onboarding friction.
• Trust Signals: Complete legal documentation increases user confidence in third-party integrations.

According to the source code in .agents/skills/plugin-creator/references/plugin-json-spec.md, these fields are optional but strongly recommended for all production plugins.

Summary

• Add privacyPolicyURL and termsOfServiceURL to .codex-plugin/plugin.json in your plugin's directory
• Both fields require valid HTTPS URLs starting with https://
• The manifest file resides at plugins/<name>/.codex-plugin/plugin.json
• Validate changes using npm run lint before committing to the main branch
• Reference existing implementations in plugins/zotero/, plugins/zoom/, or plugins/superhuman/ for guidance

Frequently Asked Questions

What format must the privacy policy and terms of service URLs use?

Both privacyPolicyURL and termsOfServiceURL must be valid HTTPS URLs starting with https://. HTTP endpoints are not accepted by the OpenAI plugin validation system.

Are these fields required for all OpenAI plugins?

These fields are optional according to the Plugin JSON Specification, but they are strongly recommended for production plugins. Most published plugins in the repository, including Zotero and Zoom, include both fields to ensure compliance and user transparency.

Where can I find the official JSON schema for the plugin manifest?

The complete schema specification is located at .agents/skills/plugin-creator/references/plugin-json-spec.md in the openai/plugins repository. This document defines all valid fields, including the optional privacyPolicyURL and termsOfServiceURL parameters.

How do I validate my plugin.json changes before submitting?

Run npm run lint from the repository root to execute the validation scripts. These scripts check that your manifest conforms to the required schema, verifies HTTPS formatting for legal URLs, and ensures all mandatory fields are present.

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