What Is the Purpose of the `api` Key in a Claude Plugin Manifest?

The api key in a Claude plugin manifest defines the HTTP API that the plugin calls when Claude executes its tools, acting as a single source of truth for base endpoint configuration, authentication handling, and schema validation.

In the anthropics/claude-plugins-community repository, each plugin declares its external service integration through a manifest file. The api key sits at the top level of this manifest and governs how every tool in the plugin communicates with third-party services. Understanding this key is essential for building secure, maintainable, and portable Claude plugins.

How the api Key Defines the Base Endpoint

The primary function of the api key is to specify a base URL that all tools in the plugin share. Individual tool definitions then declare only their relative paths, which Claude concatenates with this base.

In plugins/*/.claude-plugin/manifest.json, the structure looks like this:

{
  "name": "weather-forecast",
  "description": "Fetches current weather data.",
  "api": {
    "url": "https://api.openweathermap.org/data/2.5"
  },
  "tools": [
    {
      "name": "getCurrentWeather",
      "path": "/weather",
      "method": "GET",
      "query": {
        "q": "{city}",
        "units": "metric"
      }
    }
  ]
}

When Claude executes getCurrentWeather, it automatically prefixes the tool's path (/weather) with the api.url, forming the complete request URL: https://api.openweathermap.org/data/2.5/weather?q={city}&units=metric.

This centralization means you can change environments without editing individual tools. A production manifest might use https://api.example.com/v1 while a development manifest uses https://dev.api.example.com/v1—the tools remain identical.

Authentication Configuration Through the api Key

The api key also enables declarative authentication handling. Rather than hardcoding credentials in tool definitions, you specify an auth object that Claude's runtime applies to every request using that API.

{
  "api": {
    "url": "https://api.stripe.com/v1",
    "auth": {
      "type": "header",
      "headerName": "Authorization",
      "valueTemplate": "Bearer {secret}"
    }
  },
  "tools": [
    {
      "name": "listCustomers",
      "path": "/customers",
      "method": "GET"
    }
  ]
}

Here, Claude injects the user-supplied secret into the Authorization header for every request to api.stripe.com. The supported authentication patterns and their schemas are defined in plugins/*/.claude-plugin/api-schema.json, which validates that auth objects contain required fields like type, headerName (for header-based auth), or keyName (for query-parameter-based auth).

Schema Validation of the api Object

Every api entry is validated against the API schema located at plugins/*/.claude-plugin/api-schema.json. This JSON Schema enforces structural integrity before a plugin is published, preventing runtime failures from malformed configurations.

The schema typically defines allowed fields:

• url (string, required): The base endpoint
• auth (object): Authentication configuration
• timeout (number): Request timeout in milliseconds
• retry (object): Retry policy for failed requests

Validation occurs during the plugin packaging process, ensuring that only well-formed api configurations reach production.

File Structure and Key Locations

The following files work together to implement the api key functionality:

• plugins/*/.claude-plugin/manifest.json — Contains the top-level api definition
• plugins/*/.claude-plugin/api-schema.json — Validates the api object structure
• plugins/*/.claude-plugin/tools/*.json — Individual tool specifications that reference the shared api configuration
• docs/plugin-manifest.md — Documentation describing manifest fields and their purposes

Summary

• The api key in a Claude plugin manifest establishes the base URL for all HTTP requests made by that plugin's tools.
• It supports centralized authentication configuration, keeping credentials out of individual tool definitions.
• The api-schema.json file validates api objects against a strict JSON Schema, catching configuration errors early.
• Environment portability is simplified: change the api.url value to switch between staging, development, and production without modifying tool code.

Frequently Asked Questions

What happens if I omit the api key from my plugin manifest?

A plugin manifest without an api key cannot define HTTP-based tools. The Claude runtime requires this key to resolve request URLs. If your plugin only provides static resources or computation without external API calls, you may not need it—but such plugins are uncommon in the anthropics/claude-plugins-community ecosystem.

Can a single plugin define multiple api endpoints?

No. The manifest structure supports exactly one top-level api object. If your plugin needs to communicate with multiple distinct services, you must either create separate plugins or route all requests through a single intermediary service that handles the distribution.

How does Claude handle api authentication secrets securely?

Claude never stores secrets in the manifest itself. The auth configuration in api.auth uses templates like {secret} that reference credentials supplied by the end user at runtime. These values are injected into requests at execution time and are not persisted in plugin files or logs, as specified in the authentication patterns documented in docs/plugin-manifest.md.

Where can I find examples of production api configurations?

Browse the plugins/ directory in the anthropics/claude-plugins-community repository. Each subdirectory containing a .claude-plugin/manifest.json demonstrates real-world api usage patterns, including variations for OAuth, API keys, and custom header authentication.

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