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

> Choose between Bearer token and SigV4 authentication for your AWS DevOps Agent. Discover which method best suits your single or multi-space orchestration and IAM security needs easily.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: comparison
- Published: 2026-06-26

---

**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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.

```bash

# 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) for Bearer authentication:

```json
{
  "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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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.

```bash

# 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) configuration for SigV4 uses command execution rather than HTTP headers:

```json
{
  "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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) configuration. Remove the `DEVOPS_AGENT_TOKEN` variable, ensure your AWS credentials are configured, and regenerate the [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/running-release-tests/SKILL.md) and [`investigating-incidents-with-aws-devops-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.