Bearer Token vs SigV4 Authentication for AWS DevOps Agent: Choosing the Right Method

The AWS DevOps Agent supports both Bearer token and AWS Signature Version 4 (SigV4) authentication, with Bearer tokens offering simpler single-space access while SigV4 enables multi-space orchestration and IAM-based security.

The Agent Toolkit for AWS provides dual authentication paths for connecting to the AWS DevOps Agent MCP (Microservice Control Plane). Your choice between Bearer tokens and SigV4 directly impacts routing capabilities, credential management complexity, and multi-tenant support. Understanding the implementation details in the setup-devops-agent skill helps you configure the correct method for your operational requirements.

Authentication Methods Overview

The toolkit authenticates via the MCP endpoint https://connect.aidevops.${REGION}.api.aws/mcp using one of two mutually exclusive approaches. According to the source code in plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md, the system evaluates available credentials and presents a decision matrix when both methods are detected (lines 67-72).

Bearer Token authentication requires only two environment variables and sends an Authorization: Bearer header directly to the MCP endpoint. SigV4 authentication leverages uvx mcp-proxy-for-aws to locally sign requests using your AWS credential chain, enabling advanced features like multi-space discovery.

Bearer Token Authentication

Bearer tokens provide the fastest path to a working connection when you only need access to a single AgentSpace.

Configuration and Setup

Set the DEVOPS_AGENT_TOKEN and DEVOPS_AGENT_REGION environment variables. The toolkit validates connectivity by sending a JSON-RPC request with the Bearer header to the regional endpoint.

# Export credentials

export DEVOPS_AGENT_TOKEN="eyJhbGciOi...<your-token>"
export DEVOPS_AGENT_REGION="us-west-2"

# Verify connectivity

curl -s -w "\nHTTP_STATUS: %{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEVOPS_AGENT_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp"

As implemented in SKILL.md (lines 89-104), successful responses return HTTP 200 with a result.tools array. Authentication failures (401/403) trigger token-specific troubleshooting steps.

Use Cases and Limitations

Bearer tokens excel in scenarios where you lack comprehensive AWS IAM permissions or only operate within one AgentSpace. However, the token scopes strictly to a single space, and you must manually refresh it upon expiration. Multi-space operations—such as those required by running-release-tests or investigating-incidents-with-aws-devops-agent skills—are unavailable with this method.

Configure your .mcp.json for Bearer authentication:

{
  "mcpServers": {
    "aws-devops-agent": {
      "type": "http",
      "url": "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp",
      "headers": {
        "Authorization": "Bearer ${DEVOPS_AGENT_TOKEN}"
      },
      "timeout": 120000
    }
  }
}

Place this file at ${CLAUDE_PLUGIN_ROOT}/.mcp.json or project-scoped .mcp.json as defined in lines 45-61 of the skill implementation.

AWS Signature Version 4 (SigV4) Authentication

SigV4 integrates the DevOps Agent with your existing AWS identity infrastructure, enabling automated credential rotation and cross-service permissions.

Configuration and Setup

Install uvx and configure AWS credentials via SSO or static keys. The toolkit invokes uvx mcp-proxy-for-aws@latest to create a local signing proxy that intercepts MCP requests and applies SigV4 signatures.

# Install uvx

brew install uv          # macOS

# or

curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux

# Configure AWS SSO

aws configure sso --profile devops-agent
aws sso login --profile devops-agent
export AWS_PROFILE=devops-agent
export DEVOPS_AGENT_REGION="us-west-2"

# Verify AWS credentials

aws sts get-caller-identity

# Test connectivity via signing proxy

timeout 30 bash -c '
{
  echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"setup-check\",\"version\":\"1.0\"}}}"
  sleep 0.5
  echo "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"
  sleep 0.5
  echo "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"
  sleep 8
} | uvx mcp-proxy-for-aws@latest "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp" \
  --service aidevops --region "$DEVOPS_AGENT_REGION"
'

The implementation (lines 107-128) expects the tools list in the second output line. Credential failures are diagnosed by checking aws sts get-caller-identity.

Multi-Space Routing Capabilities

Only SigV4 connections support the list_agent_spaces operation. After authentication, the toolkit discovers available AgentSpaces and generates routing configurations. This capability is mandatory for skills like running-release-tests and investigating-incidents-with-aws-devops-agent, which require cross-space coordination.

The .mcp.json configuration for SigV4 uses command execution rather than HTTP headers:

{
  "mcpServers": {
    "aws-devops-agent": {
      "command": "uvx",
      "timeout": 120000,
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://connect.aidevops.us-west-2.api.aws/mcp",
        "--service", "aidevops",
        "--region", "us-west-2"
      ]
    }
  }
}

How the Agent Toolkit Decides Between Methods

The setup-devops-agent skill implements a decision matrix that evaluates your environment before establishing a connection. As documented in SKILL.md (lines 67-72):

1. If both Bearer token and AWS credentials are present, the toolkit prompts you to select your preferred method.
2. If only Bearer variables are set, it proceeds with token-based authentication.
3. If only AWS credentials are available, it configures the SigV4 proxy.
4. If neither is detected, it initiates an interactive setup workflow asking which method to configure.

This logic ensures that the authentication method aligns with your available credentials and operational needs without manual configuration file editing.

Summary

• Bearer tokens require only DEVOPS_AGENT_TOKEN and DEVOPS_AGENT_REGION, support single AgentSpace access, and work without AWS IAM permissions.
• SigV4 authentication requires uvx and valid AWS credentials, enables multi-space routing via list_agent_spaces, and integrates with IAM roles and SSO.
• The decision matrix in SKILL.md (lines 67-72) automatically selects or prompts for the appropriate method based on detected credentials.
• Multi-space operations—including release testing and incident investigation—require SigV4 and are unavailable with Bearer tokens.
• Authentication preferences persist in .mcp.json using either HTTP header injection (Bearer) or command proxy execution (SigV4).

Frequently Asked Questions

Which authentication method is more secure for production use?

SigV4 is generally preferred for production because it leverages AWS IAM policies, supports temporary credentials via STS, and integrates with AWS SSO for centralized identity management. Bearer tokens are long-lived strings that must be manually rotated and offer no fine-grained IAM integration. However, Bearer tokens reduce the blast radius to a single AgentSpace, which may suit isolated development environments.

Can I switch from Bearer token to SigV4 without reinstalling the toolkit?

Yes, you can switch methods by updating your environment variables and .mcp.json configuration. Remove the DEVOPS_AGENT_TOKEN variable, ensure your AWS credentials are configured, and regenerate the .mcp.json file using the SigV4 template. The toolkit will detect the new credential type on its next initialization and prompt you to confirm the change (lines 67-72).

Why does multi-space routing require SigV4 instead of Bearer tokens?

Multi-space routing requires IAM permissions to enumerate and access multiple AgentSpaces. The list_agent_spaces operation checks your AWS identity against service policies to determine accessible spaces. Bearer tokens are pre-signed URLs scoped to a single space and do not carry IAM identity assertions, making them incapable of cross-space authorization checks required by skills in running-release-tests/SKILL.md and investigating-incidents-with-aws-devops-agent/SKILL.md.

What happens when my Bearer token expires?

The toolkit returns 401/403 errors and triggers token-specific troubleshooting steps as defined in SKILL.md (lines 89-104). You must manually obtain a new token from the DevOps Operator web UI and update the DEVOPS_AGENT_TOKEN environment variable. Unlike SigV4—which can automatically refresh credentials via AWS SSO or IAM role chaining—Bearer tokens require manual intervention upon expiration.

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