Authentication Modes for the scan-plugins GitHub Action: API Key vs. Workload Identity Federation

The scan-plugins action supports two mutually exclusive authentication modes: a static Anthropic API key for simple integrations, and Workload Identity Federation (WIF) using GitHub OIDC tokens for secret-free, short-lived credential exchange.

The scan-plugins action in the anthropics/claude-plugins-community repository validates Claude plugin submissions against security policies. Understanding the authentication modes for the scan-plugins action is essential for securely enabling Claude policy scans in your CI/CD pipeline, as the action requires valid credentials to access Anthropic's scanning services.

Static API Key Authentication Mode

The simplest authentication mode uses a classic Anthropic API key passed directly to the action. When the anthropic-api-key input is non-empty, the action sets the environment variable SCAN_HAS_AUTH=true and proceeds with the full Claude policy scan.

In .github/actions/scan-plugins/action.yml, the input is defined at lines 16-22 alongside validation logic that checks for credential presence. The SCAN_HAS_AUTH flag is established in the environment block at lines 29-33, signaling downstream steps that authenticated scanning is available. The actual API key is consumed by .github/actions/scan-plugins/scripts/scan.sh to authenticate API requests against the Claude service.

Workload Identity Federation Authentication Mode

For organizations avoiding long-lived secrets, the Workload Identity Federation (WIF) mode leverages GitHub-issued OIDC tokens to obtain short-lived Anthropic tokens. This mode requires three inputs: anthropic-federation-rule-id, anthropic-organization-id, and anthropic-service-account-id.

When enabled, the Mint GitHub OIDC token step (lines 66-104 of action.yml) exchanges the GitHub OIDC token for an Anthropic token and injects the following environment variables:

• ANTHROPIC_FEDERATION_RULE_ID
• ANTHROPIC_ORGANIZATION_ID
• ANTHROPIC_SERVICE_ACCOUNT_ID
• ANTHROPIC_IDENTITY_TOKEN_FILE

Your workflow must declare permissions: id-token: write to support this token minting process. The federated token is then passed to the scanning scripts instead of a static API key.

Authentication Precedence and Fallback Behavior

The two authentication modes follow strict precedence rules implemented in the action's control flow. If you provide both anthropic-api-key and anthropic-federation-rule-id, Workload Identity Federation takes precedence and the static key is ignored.

If neither authentication mode is configured, the action executes the Skip if no Anthropic auth configured step (lines 35-41 of action.yml). This short-circuits the workflow to run only the deterministic static pin check via .github/actions/scan-plugins/lib/pin-check.sh, effectively bypassing the Claude policy scan while still validating plugin manifests.

Implementation Details in action.yml

The authentication logic is centralized in .github/actions/scan-plugins/action.yml across four critical sections:

• Lines 16-22: Define the anthropic-api-key input and anthropic-federation-rule-id input alongside initial validation logic.
• Lines 29-33: Establish the SCAN_HAS_AUTH environment flag based on whether anthropic-api-key is populated.
• Lines 35-41: Implement the early exit logic that skips authenticated scanning when no credentials are present.
• Lines 66-104: Contain the OIDC token minting and exchange process for Workload Identity Federation.

The scanning script at .github/actions/scan-plugins/scripts/scan.sh consumes either the ANTHROPIC_API_KEY environment variable or the federated token file to execute the policy analysis, while .github/actions/scan-plugins/lib/pin-check.sh operates independently of authentication state.

Complete Configuration Examples

Using Static API Key Authentication

- uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@v1
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    marketplace-path: .claude-plugin/marketplace.json
    fail-on-findings: "true"

Using Workload Identity Federation

permissions:
  id-token: write   # Required for WIF token minting

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@v1
        with:
          anthropic-federation-rule-id: ${{ secrets.ANTHROPIC_FEDERATION_RULE_ID }}
          anthropic-organization-id: ${{ secrets.ANTHROPIC_ORG_ID }}
          anthropic-service-account-id: ${{ secrets.ANTHROPIC_SVAC_ID }}
          marketplace-path: .claude-plugin/marketplace.json

Both Inputs Present (Federation Wins)

- uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@v1
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    anthropic-federation-rule-id: ${{ secrets.ANTHROPIC_FEDERATION_RULE_ID }}
    # The action ignores the static key and uses WIF

Summary

• Static API key mode: Pass anthropic-api-key to authenticate directly with Anthropic services; suitable for simple repository setups.
• Workload Identity Federation mode: Configure anthropic-federation-rule-id, anthropic-organization-id, and anthropic-service-account-id to use OIDC tokens; requires permissions: id-token: write.
• Precedence rule: When both modes are configured, WIF takes precedence and the static key is ignored.
• Fallback behavior: Without either credential, the action skips the Claude policy scan and runs only the static pin check defined in lib/pin-check.sh.
• Source location: All authentication logic is implemented in .github/actions/scan-plugins/action.yml with specific handling at lines 16-41 and 66-104.

Frequently Asked Questions

What happens if I provide both a static API key and Workload Identity Federation credentials?

The federated mode takes precedence. According to the source code in action.yml, when anthropic-federation-rule-id is present, the action uses the OIDC token exchange flow and ignores the anthropic-api-key input entirely.

Can I run the scan-plugins action without any authentication?

Yes, but functionality is limited. If you omit both anthropic-api-key and anthropic-federation-rule-id, the action triggers the early exit logic at lines 35-41 and performs only the deterministic static pin check via lib/pin-check.sh, skipping the Claude policy scan.

What permissions are required for Workload Identity Federation?

Your workflow must include permissions: id-token: write to allow the action to mint GitHub OIDC tokens. The action then exchanges these tokens for Anthropic credentials using the inputs provided.

Where does the action handle OIDC token minting?

The Mint GitHub OIDC token step in .github/actions/scan-plugins/action.yml (lines 66-104) handles the OIDC token exchange. This step sets the ANTHROPIC_IDENTITY_TOKEN_FILE and related environment variables used by the scanning scripts.

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