Your Traces Can Now Reach CloudWatch With One Header
The workloads that never sent a trace
Sending OpenTelemetry traces to CloudWatch has meant signing every request with AWS Signature Version 4. Inside AWS that costs nothing, because the workload already has a role and the ADOT SDKs handle the signing. Outside AWS it’s a small project. The server on premises or the VM in another cloud needs AWS credentials from somewhere, and the collector needs the sigv4auth extension to use them.
Some clients can’t do it at all. A third-party tool that gives you one field for an endpoint and one for a header has nowhere to put a signature. A CI job can sign a request, but few people will write that for a span about a deploy. So those workloads often end up without traces in CloudWatch, because getting them there costs more than it seems worth.
On November 3, AWS added a much cheaper way in. If you’d rather read code first, the sample repo sets up everything a key needs in CloudFormation, CDK, or Terraform.
What AWS shipped
CloudWatch now accepts API keys (bearer tokens) for OpenTelemetry traces sent to the X-Ray OTLP traces endpoint (announcement). Any OTLP/HTTP client that can set an Authorization header can use one, including the OpenTelemetry Collector and the SDK exporters.
Under the hood, the key is an IAM service-specific credential for xray.amazonaws.com, owned by an IAM user (docs). AWS provides a managed policy for that user, AWSXRayAPIKeyAccess, which grants the two permissions involved: xray:CallWithBearerToken to authenticate with a key, and xray:PutTraceSegments to send spans.
Traces sent either way get the same CloudWatch capabilities, including Transaction Search, Application Signals, and CloudWatch Omni. SigV4 remains the recommended method, and the ADOT SDKs keep using it with no changes.

What it looks like
For a CI job, sending a span is now one HTTP call:
curl -X POST "https://xray.us-east-1.amazonaws.com/v1/traces" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $XRAY_API_KEY" \
-d @spans.json
For a collector, bearertokenauth replaces sigv4auth, and the AWS credentials go away with it:
extensions:
bearertokenauth:
token: "${env:XRAY_API_KEY}"
exporters:
otlphttp/traces:
compression: gzip
traces_endpoint: "https://xray.us-east-1.amazonaws.com/v1/traces"
auth:
authenticator: bearertokenauth
I put a sample of this in a sample repo: a stack in CloudFormation, CDK, and Terraform that turns on Transaction Search and creates the key’s user, its secret, and the IAM policies below, plus a collector config, a Python SDK example, a curl script, and scripts that create and rotate keys. I validated the stacks but haven’t deployed them, so try them in a test account first.
You traded signing for a secret
I think this is the right trade for these workloads, as long as teams treat it as a trade. SigV4 with short-term credentials limits how long a stolen credential is useful. An API key is a long-lived string that lives wherever you put it, and AWS says plainly that you should use one only where short-term credentials aren’t practical.
The good news is how little a key can do. It works only for sending spans to the OTLP endpoint; it can’t read trace data or call other X-Ray APIs. So a leaked key shouldn’t expose your traces, but it can still fill them with junk until you revoke it, and that’s a bad thing to discover in the middle of an incident.
Scope depends on you, though. A request has exactly the permissions of the IAM user that owns the key, so the protection comes from giving that user nothing else. I’d create one user per integration, attach only the managed policy, and never add a key to a user that does other work. That also means revoking one leaked key doesn’t take every other pipeline down with it.
What I’d check before handing out a key
Turn on Transaction Search first. The OTLP traces endpoint requires it, because that’s what sends spans to CloudWatch Logs.
Set an expiry, because the default is forever. A key created without a credential age never expires. You can set 1 to 36,600 days per key, but the setting that holds up is the iam:ServiceSpecificCredentialAgeDays condition key, which refuses keys without a short enough expiry. The sample repo has a policy that caps them at 90 days.
Plan for the day a key expires. The endpoint returns HTTP 403 for an invalid, expired, or inactive key, and also when the user lacks either permission. When I pointed the sample’s Python SDK at a local mock endpoint with a bad key, the exporter logged the 403 and the program carried on normally. That’s the right behavior for an application, but it means an expired key can look like a quiet trace dashboard rather than an outage. Alert on exporter failures, and put rotation on a schedule that runs before expiry.
Rehearse rotation once. IAM allows two X-Ray keys per user so you can swap without downtime: create the second key, deploy it, set the old one to inactive, confirm traces still arrive, then delete it. Status changes take up to about five minutes to apply, and you need AWS credentials to manage keys, because a key can’t manage itself.
Turn on CloudTrail data events if you want an audit trail. Requests made with a key are recorded as PutTraceSegments data events with "callWithBearerToken": true, which SigV4 requests don’t include, so you can find every use of a key. CloudTrail doesn’t log data events by default, and they won’t help with an incident that started before you enabled them.
Check two smaller things. Requests must use HTTPS, and the docs list the supported Regions. If you send spans to custom log groups with the x-aws-log-group and x-aws-log-stream headers, the user also needs permission to write to those groups, so the managed policy alone won’t be enough.
Keep the key out of config files. Read it from a mounted secret with filename, or from an environment variable injected by your secrets manager. Collector configs tend to get committed.
Where I’d start
Pick one workload that has no traces in CloudWatch today because SigV4 was too much work, and a CI pipeline is a good candidate. Deploy the sample repo’s stack, which turns on Transaction Search and creates one IAM user, then create a 30-day key and send a span for each deploy.
If you already run SigV4 somewhere, leave it alone. This is for the workloads that had no good option, not a simpler replacement for the ones that do.
What’s the one system you’ve never been able to get traces from, and would a static header have fixed it?
Sources
- Amazon CloudWatch now supports API keys for OpenTelemetry traces, AWS What’s New, Nov 3, 2026
- Setting up bearer token authentication for traces, AWS X-Ray Developer Guide
- OTLP Endpoints, Amazon CloudWatch User Guide
- Sample code for this post, GitHub
The opinions on this blog are my own and do not represent the views of my employer.