Setting up bearer token authentication for Metrics

Before you can send metrics using bearer token authentication with the CloudWatch OTLP endpoint, you need to:

Option 1: Quick start using the AWS console

The AWS Management Console provides a streamlined workflow to generate API keys for OTLP endpoint access.

The console automatically:

Option 2: Manual setup

If you prefer more control over the IAM configuration or need to customize permissions, you can set up the OTLP endpoint access manually.

Step 1: Create an IAM user

Create an IAM user for metric ingestion:

Step 2: Generate service-specific credentials (API key)

Generate the CloudWatch Metrics API key using the CreateServiceSpecificCredential API. You can also use the create-service-specific-credential AWS CLI command. For the credential age, you can specify a value between 1–36600 days. If you don't specify a credential age, the API key won't expire.

To generate an API key with an expiration of 30 days:

aws iam create-service-specific-credential \
    --user-name cloudwatch-metrics-api-key-user \
    --service-name cloudwatch.amazonaws.com \
    --credential-age-days 30

The response is a ServiceSpecificCredential object. The ServiceCredentialSecret value is your CloudWatch Metrics API key (bearer token).

Step 3: Send metrics

You can immediately send metrics to the OTLP endpoint using your bearer token:

curl -X POST "https://monitoring.us-east-1.amazonaws.com/v1/metrics" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{"resourceMetrics":[]}'

The endpoint accepts both application/json and application/x-protobuf content types.

Control permissions for generating and using CloudWatch Metrics API keys

Controlling the generation of CloudWatch Metrics API keys

The iam:CreateServiceSpecificCredential action controls the generation of a service-specific key (such as a CloudWatch Metrics API key). You can scope this action to IAM users as a resource to limit the users for which a key can be generated.

You can use the following condition keys to impose conditions on the permission for the iam:CreateServiceSpecificCredential action:

Controlling the usage of CloudWatch Metrics API keys

The cloudwatch:CallWithBearerToken action controls the use of a CloudWatch Metrics API key. To prevent an identity from using CloudWatch Metrics API keys, attach a policy that denies the cloudwatch:CallWithBearerToken action to the IAM user associated with the key.

Example policies

Prevent an identity from generating and using CloudWatch Metrics API keys:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DenyCWMetricsAPIKeys",
            "Effect": "Deny",
            "Action": [
                "iam:CreateServiceSpecificCredential",
                "cloudwatch:CallWithBearerToken"
            ],
            "Resource": "*"
        }
    ]
}

Prevent an identity from using CloudWatch Metrics API keys:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "cloudwatch:CallWithBearerToken",
            "Resource": "*"
        }
    ]
}

Allow the creation of CloudWatch Metrics keys only if they expire within 90 days:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iam:CreateServiceSpecificCredential",
            "Resource": "arn:aws:iam::123456789012:user/username",
            "Condition": {
                "StringEquals": {
                    "iam:ServiceSpecificCredentialServiceName": "cloudwatch.amazonaws.com"
                },
                "NumericLessThanEquals": {
                    "iam:ServiceSpecificCredentialAgeDays": "90"
                }
            }
        }
    ]
}

Using bearer tokens with the OpenTelemetry Collector

When using bearer tokens, you do not need the sigv4auth extension. Use the bearertokenauth extension to securely provide your API key from a file or environment variable:

extensions:
  bearertokenauth:
    filename: "/etc/otel/cw-api-key"

exporters:
  otlphttp:
    tls:
      insecure: false
    endpoint: https://monitoring.us-east-1.amazonaws.com/v1/metrics
    auth:
      authenticator: bearertokenauth

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    send_batch_size: 200
    timeout: 10s

service:
  extensions: [bearertokenauth]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

Alternatively, you can reference an environment variable instead of a file:

extensions:
  bearertokenauth:
    token: "${env:CW_API_KEY}"

Rotating API keys

Regularly rotating your API keys reduces the risk of unauthorized access. We recommend establishing a rotation schedule that aligns with your organization's security policies.

Rotation process

To rotate an API key without interrupting metric delivery, follow this procedure:

Monitoring key expiration

To check the creation date and status of your existing API keys, use the list-service-specific-credentials command:

aws iam list-service-specific-credentials \
    --user-name cloudwatch-metrics-api-key-user \
    --service-name cloudwatch.amazonaws.com

The response includes CreateDate and Status for each credential. Use this information to identify keys that are approaching expiration or have been active longer than your rotation policy allows.

Responding to a compromised API key

If you suspect that an API key has been compromised, take the following steps immediately:

You can also use the following IAM API operations to manage compromised keys:

Security best practices for API keys

Follow these best practices to protect your CloudWatch Metrics API keys:

Logging API key usage with CloudTrail

You can use AWS CloudTrail to log data events for CloudWatch Metrics OTLP ingestion. CloudWatch emits AWS::CloudWatch::Metric data events for calls to the OTLP endpoint, enabling you to audit metric ingestion activity including API key usage.

This selector captures all OTLP metric ingestion events (both SigV4 and bearer token authenticated). To identify bearer token usage specifically, filter by the IAM user name associated with your API key (for example, cloudwatch-metrics-api-key-user).