# How to Specify Authentication Methods in the Claude Plugin Manifest

> Specify authentication methods in your Claude plugin manifest using the auth object. Seamlessly handle OAuth, API keys, or no-auth for Claude Code and Claude Cowork.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json).

```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.

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json).

```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.

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), which catalogs plugins and their authentication requirements.

## Summary

- Declare authentication in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) (OAuth) and [`testdino/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json)) if your plugin accesses public APIs or local resources that do not require credentials.