# How to Configure Sensitive userConfig Fields Like API Keys in plugin.json

> Secure your Claude plugin API keys by marking sensitive fields in plugin.json with "sensitive": true. Protect secrets locally, mask them in logs, and exclude them from the marketplace.

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

---

**Mark sensitive fields in your Claude plugin's [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) with `"sensitive": true` to ensure API keys and secrets are stored locally in the user's `~/.claude/` directory, masked in logs, and excluded from the public marketplace manifest.**

Claude plugins from the `anthropics/claude-plugins-community` repository rely on the `userConfig` section in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) to collect user-specific settings. When these settings include credentials like API keys, you must configure sensitive userConfig fields properly to prevent accidental exposure in version control or marketplace listings.

## Understanding the userConfig Schema Structure

The `userConfig` object in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) defines configuration fields as typed properties that Claude Code prompts for during installation. Each field supports standard JSON Schema attributes plus a security-critical `sensitive` boolean flag.

### Required Properties for Sensitive Fields

When defining an API key or token, include these properties:

- **type** – Must be `"string"` for text-based secrets
- **description** – User-facing prompt text shown during installation
- **sensitive** – Boolean flag triggering secret handling behavior
- **required** – Ensures the installer prompts for the value before activation

### Optional Properties

- **default** – Fallback value when the field is not required (omit for secrets to avoid hardcoding values)

## The `sensitive` Flag Security Model

Setting `"sensitive": true` activates three protective mechanisms in the Claude plugin framework:

1. **Local Storage Only** – Values are written to `~/.claude/<plugin-name>.json` on the user's machine, never committed to the repository or marketplace manifest
2. **UI Masking** – Input is hidden during CLI prompts and redacted in log output
3. **Process Isolation** – The secret is injected only into the plugin's runtime environment, unavailable to other agents or the marketplace listing

According to the source code in [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json), this pattern is explicitly used for the QuickDesign plugin's access token configuration.

## Complete Configuration Example

The QuickDesign plugin demonstrates best practices for handling bearer tokens:

```json
{
  "name": "quickdesign",
  "description": "AI-generated video design plugin.",
  "version": "2.1.0",
  "userConfig": {
    "accessToken": {
      "type": "string",
      "description": "Bearer token for the QuickDesign service.",
      "sensitive": true,
      "required": true
    }
  }
}

```

In `anthropics/claude-plugins-community`, the validation script specifically checks this file to ensure `accessToken` carries the `sensitive` flag before allowing publication.

For plugins without secrets, such as TestDino, omit the `userConfig` section entirely:

```json
{
  "name": "testdino",
  "description": "Inspect test runs via a remote MCP server.",
  "version": "1.0.0"
}

```

This file is located at [`testdino/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json) and serves as the reference for non-sensitive configurations.

## CI Validation and Leak Prevention

The repository enforces secret safety through [`.github/actions/validate-plugins/scripts/41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/41-validate-aux-files.sh). This script validates that:

- Any field marked `sensitive` or `secret` (legacy syntax) does not appear in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)
- Credentials fields include the appropriate security flag

If validation fails, the plugin cannot be published to the community marketplace, ensuring that no secret values leak into the public repository.

## Runtime Behavior and Installation Flow

When users install your plugin, Claude Code executes this sequence:

1. **Parse** – Reads `userConfig` from [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)
2. **Prompt** – Requests missing required values, masking sensitive input with asterisks
3. **Persist** – Writes secrets to the user's local config directory (`~/.claude/<plugin-name>.json`)
4. **Inject** – Provides the value to the plugin's MCP server at runtime via environment variables or tool arguments

The framework guarantees these values never transit back to the repository or appear in telemetry logs.

## Legacy Support for `secret` Fields

Older plugin manifests may use `"secret": true` instead of `sensitive`. The validation script in [`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh) accepts both flags for backward compatibility, but new plugins should standardize on `sensitive` for forward compatibility with future marketplace schema versions.

## Summary

- **Mark secrets with `sensitive: true`** in `userConfig` to protect API keys and tokens from exposure
- **Validation occurs** in [`.github/actions/validate-plugins/scripts/41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/41-validate-aux-files.sh), blocking leaks before publication to the marketplace
- **Local storage** isolates secrets in `~/.claude/<plugin-name>.json`, keeping them out of version control and shared manifests
- **Runtime injection** makes secrets available only to the specific plugin process through environment variables or tool arguments
- **Reference implementations** exist in [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) (with secrets) and [`testdino/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json) (without sensitive fields)

## Frequently Asked Questions

### What happens if I forget to mark an API key as sensitive?

The CI validator will reject your plugin during the marketplace submission process. If somehow bypassed, the unmarked value would appear in plain text within the public [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file and could be committed to the repository, exposing user credentials to anyone browsing the source.

### Where exactly are sensitive values stored on the user's machine?

Claude Code writes sensitive configuration to `~/.claude/<plugin-name>.json` in the user's home directory. This file has restrictive permissions and is automatically excluded from the plugin's git repository through `.gitignore` generation, ensuring secrets remain on the local filesystem only.

### Can I use default values with sensitive fields?

No. The combination of `"sensitive": true` and `"default"` is invalid and will fail validation. Default values imply hardcoded secrets, which defeats the purpose of user-specific configuration. Always require user input for actual credentials by setting `"required": true` without a default.

### How do I migrate from the legacy `secret` flag to `sensitive`?

Update your [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) to use `"sensitive": true` instead of `"secret": true`. The validation script at [`41-validate-aux-files.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/41-validate-aux-files.sh) recognizes both flags during the transition period, but future versions of the marketplace schema may deprecate `secret` in favor of the standardized `sensitive` property.