How to Specify Authentication Methods in the Claude Plugin Manifest

Yes, you can specify authentication methods in the Claude plugin manifest by declaring an auth object (or array of objects) in the .claude-plugin/plugin.json file, which enables Claude Code or Claude Cowork to automatically handle OAuth flows, API keys, or no-auth scenarios.

The anthropics/claude-plugins-community repository defines the specification for Claude plugins, which rely on a manifest file to declare capabilities and security requirements. By configuring the auth section in this manifest, you enable Claude to automatically guide users through login flows and securely store credentials for subsequent tool calls.

The Auth Object Structure

In the .claude-plugin/plugin.json manifest, the top-level auth object describes the authentication flow the plugin requires. When a plugin is installed, Claude reads this section and automatically offers an "Authenticate" button to the user.

The auth object supports the following fields:

Field	Description
type	The authentication scheme (oauth, apiKey, or none).
authorizationUrl	(OAuth) URL shown to the user for the consent screen.
tokenUrl	(OAuth) URL that exchanges the authorization code for an access token.
scopes	(OAuth) List of permission scopes the plugin requires.
headerName	(API Key) HTTP header to add (Authorization, X-API-Key, etc.).
queryParam	(API Key) Query-string parameter name if the key is passed in the URL.
refresh	Optional object describing how to refresh expired tokens.

As implemented in anthropics/claude-plugins-community, the Claude plugin runtime inspects this auth object when the plugin loads and builds a UI that drives the chosen flow, injecting the resulting token into the tool-call context.

Supported Authentication Types

OAuth 2.0 Authentication

For services requiring OAuth 2.0, specify the type as "oauth" and provide the necessary endpoints. The QuickDesign plugin in the repository demonstrates this pattern in quickdesign/.claude-plugin/plugin.json.

{
  "name": "my-oauth-plugin",
  "description": "Demo plugin that uses OAuth2 authentication",
  "auth": {
    "type": "oauth",
    "authorizationUrl": "https://example.com/oauth/authorize",
    "tokenUrl": "https://example.com/oauth/token",
    "scopes": ["read", "write"]
  },
  "tools": [
    {
      "name": "list_items",
      "description": "Fetch a list of items from the service",
      "input_schema": {}
    }
  ]
}

When the user runs claude plugin install, Claude displays an "Authenticate" button that opens the authorizationUrl. After authorization, Claude stores the token and automatically adds it to every list_items call.

API Key Authentication

For static key-based authentication, use the apiKey type and specify where Claude should inject the credential.

{
  "name": "my-api-key-plugin",
  "description": "Plugin that authenticates with a static API key",
  "auth": {
    "type": "apiKey",
    "headerName": "X-API-Key"
  },
  "tools": [
    {
      "name": "search",
      "description": "Search the service using the supplied API key",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      }
    }
  ]
}

Claude prompts the user for the API key (masked input), then adds the header X-API-Key: <provided> to every tool call.

No Authentication

If your plugin does not require authentication, explicitly set the type to "none". The TestDino plugin illustrates this configuration in testdino/.claude-plugin/plugin.json.

{
  "name": "no-auth-plugin",
  "auth": {
    "type": "none"
  },
  "tools": [...]
}

Configuring Multiple Authentication Methods

You can define multiple authentication options for the same plugin by providing an array of auth objects. This allows users to choose their preferred login method.

{
  "name": "flex-auth-plugin",
  "description": "Supports either OAuth2 or API-Key authentication",
  "auth": [
    {
      "type": "oauth",
      "authorizationUrl": "https://example.com/oauth/authorize",
      "tokenUrl": "https://example.com/oauth/token",
      "scopes": ["read"]
    },
    {
      "type": "apiKey",
      "headerName": "Authorization"
    }
  ]
}

Claude presents a choice (e.g., "Log in with OAuth" or "Enter API key"). The user selects their preferred method, and Claude uses the chosen credentials for all subsequent calls.

How Claude Processes the Manifest

When a plugin is loaded, the Claude runtime performs the following actions based on the manifest:

1. Inspection: Reads the auth section from .claude-plugin/plugin.json.
2. UI Generation: Builds a small interface that drives the specified authentication flow.
3. Credential Storage: Stores the resulting token or key in the session’s secret store.
4. Auto-Injection: Automatically includes the credential in every tool call context, respecting the security rules defined in the manifest.

The central registry for community plugins is maintained in .claude-plugin/marketplace.json, which catalogs plugins and their authentication requirements.

Summary

• Declare authentication in .claude-plugin/plugin.json using the top-level auth object.
• Support OAuth 2.0, API keys, or no authentication via the type property.
• Offer multiple methods by providing an array of authentication configurations.
• Claude automatically handles the authentication UI, secure storage, and credential injection for tool calls.
• Real-world examples are available in quickdesign/.claude-plugin/plugin.json (OAuth) and testdino/.claude-plugin/plugin.json (no auth).

Frequently Asked Questions

What file do I edit to specify authentication methods for my Claude plugin?

You edit the .claude-plugin/plugin.json file located in your plugin's root directory. Add a top-level auth field containing the authentication configuration object or array.

Can I support both OAuth and API keys in the same plugin?

Yes. Instead of a single object, set the auth field to an array containing multiple authentication configuration objects. Claude will present the user with a choice of login methods during installation.

How does Claude store the credentials obtained from authentication?

Claude stores the credentials in the session's secret store. The runtime automatically injects these credentials into the context of subsequent tool calls made by the plugin, ensuring they are available without manual handling.

Is authentication required for every Claude plugin?

No. You can set the auth.type to "none" (as demonstrated in testdino/.claude-plugin/plugin.json) if your plugin accesses public APIs or local resources that do not require credentials.

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