EC2 Metadata 401 Unauthorized? Fix IMDSv2 with curl

EC2 Instance Metadata Service (IMDS) is a service available from inside an EC2 instance that lets software retrieve information about that instance, such as its instance ID, hostname, IAM role credentials, and other metadata. EC2 exposes IMDS through 169.254.169.254, a link-local address used locally by software on the instance to reach the metadata service rather than as a normal internet-facing address.

IMDSv2 is the newer version of this service. Unlike IMDSv1, it requires a temporary session token when the instance is configured with token usage set to required. In AWS, HttpTokens=required means the instance accepts metadata requests only through IMDSv2, so a metadata GET without a valid token returns 401 Unauthorized.

From inside the instance you can normally query /latest/meta-data/ to discover available metadata categories, or /latest/meta-data/instance-id to retrieve the ID of the current instance. The examples below use instance-id throughout so the same path fails, then succeeds after you add a token.

If an EC2 instance is configured to require IMDSv2, a direct curl request to 169.254.169.254 without a token returns 401 Unauthorized. This means the request reached the EC2 metadata service, but IMDS rejected it because the request did not include the required IMDSv2 token. Security groups and routing are not the problem.

On a lab instance with HttpTokens=required, this request reproduces the failure:

curl -sS -i --connect-timeout 2 http://169.254.169.254/latest/meta-data/instance-id

HTTP/1.1 401 Unauthorized
Content-Length: 0
Date: Sun, 27 Sep 2026 02:58:48 GMT
Server: EC2ws
Connection: close
Content-Type: text/plain

401 Unauthorized confirms that IMDS answered the request. The call used IMDSv1-style access on an instance that requires a token.

The examples use RHEL 10.2 with HttpTokens=required and hop limit 1. Instance IDs, hostnames, and token values in screenshots and command output are sanitized; the workflow was tested in ap-south-1.

Quick Fix: Use an IMDSv2 Token

If this command returns 401 Unauthorized:

curl http://169.254.169.254/latest/meta-data/instance-id

The IMDSv2 token is a temporary session value used only to authenticate requests to the metadata service on that EC2 instance. It is not an AWS access key or IAM credential.

Request a token first:

TOKEN=$(curl -fsS -X PUT \
  "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600") || {
    echo "Failed to obtain IMDSv2 token"
    exit 1
}

In this command:

• -X PUT tells IMDS that you are requesting an IMDSv2 session token.
• -H adds the required HTTP header.
• 21600 requests a token lifetime of 21,600 seconds, or six hours.
• TOKEN=$(...) stores the returned token in the shell variable TOKEN.
• -f makes curl return a failure status for HTTP errors instead of allowing the response to be treated as a valid token.

Then send the token on the same metadata request:

curl -sS \
  -H "X-aws-ec2-metadata-token: ${TOKEN}" \
  http://169.254.169.254/latest/meta-data/instance-id

i-0123456789abcdef0

If the direct request returned 401 but the same metadata request succeeds after adding an IMDSv2 token, the instance is enforcing token-based IMDSv2 access. The sections below explain how to verify that setting and what to check when the token request itself fails.

Think of the token as a temporary pass for the metadata service: first obtain it, then present it with each metadata request until it expires.

Why 169.254.169.254 Returns 401

169.254.169.254 is the link-local IPv4 endpoint that workloads on the EC2 instance use to access IMDS. If IMDS returns HTTP 401, the request reached the metadata service, but it did not provide a valid token when one was required.

With IMDSv1, metadata could be retrieved with a direct GET. IMDSv2 adds a token request first. If the instance is configured to require IMDSv2 and you send the old IMDSv1-style GET, IMDS returns 401 Unauthorized.

             IMDSv1
           Application
                ↓
GET /latest/meta-data/instance-id
                ↓
              IMDS
                ↓
           instance ID

                 IMDSv2
               Application
                    ↓
          PUT /latest/api/token
                    ↓
                  IMDS
                    ↓
                  token
                    ↓
               Application
                    ↓
    GET /latest/meta-data/instance-id
Header: X-aws-ec2-metadata-token: <token>
                    ↓
                  IMDS
                    ↓
               instance ID

One reason AWS introduced IMDSv2 was to reduce the risk from server-side request forgery (SSRF). In an SSRF attack, a vulnerable application can be tricked into sending a request to another address on behalf of an attacker. Because EC2 metadata can expose sensitive information such as IAM role credentials, protecting access to IMDS is important. IMDSv2 adds an extra step: the caller must first make a PUT request to obtain a temporary token and then include that token in later metadata requests.

With HttpTokens=required, AWS expects:

• A PUT to /latest/api/token with X-aws-ec2-metadata-token-ttl-seconds
• Follow-up requests that include X-aws-ec2-metadata-token: <token>

Legacy scripts that call curl http://169.254.169.254/latest/meta-data/instance-id without the token step still reach IMDS but receive 401 Unauthorized.

Check Whether IMDSv2 Is Required

Before changing application code, confirm how the instance is configured. The console shows whether tokens are required and the hop limit for nested callers.

Where to run these commands: metadata curl commands must run from the EC2 instance because 169.254.169.254 is the instance metadata endpoint. The aws ec2 describe-instances command can run from your workstation or another system with AWS CLI credentials and permission to describe the instance.

Open the instance in the EC2 console and copy the Instance ID for CLI commands that use --instance-id:

The highlighted Instance ID is the value for --instance-ids and --instance-id in the AWS CLI.

Under Actions → Instance settings → Modify instance metadata options, check Metadata version. When it reads V2 only (token required), bare metadata GET requests without a token return HTTP 401:

Metadata version V2 only (token required) maps to HttpTokens: required in the CLI. This does not mean IMDS is disabled. Metadata is still available, but clients must use the IMDSv2 token workflow. Metadata response hop limit is the number of network hops the token PUT response may traverse (relevant for containers).

From your workstation, read the same fields under MetadataOptions:

aws ec2 describe-instances \
  --region ap-south-1 \
  --instance-ids i-0123456789abcdef0 \
  --query 'Reservations[0].Instances[0].MetadataOptions' \
  --output yaml

HttpEndpoint: enabled
HttpProtocolIpv6: disabled
HttpPutResponseHopLimit: 1
HttpTokens: required
InstanceMetadataTags: disabled
State: applied

HttpTokens: required matches V2 only (token required) in the console. State: applied means the running instance already enforces the setting.

Use and Reuse the IMDSv2 Token

Attach the token to every metadata GET (and to other IMDSv2 operations AWS documents). The header name is case-insensitive; AWS documents X-aws-ec2-metadata-token.

Fetch the instance ID with the curl command -H flag:

curl -sS -H "X-aws-ec2-metadata-token: ${TOKEN}" \
  http://169.254.169.254/latest/meta-data/instance-id

i-0123456789abcdef0

You can reuse the same token for other metadata paths until it expires:

curl -sS -H "X-aws-ec2-metadata-token: ${TOKEN}" \
  http://169.254.169.254/latest/meta-data/local-hostname

ip-10-0-1-50.ap-south-1.compute.internal

IAM role credentials under /latest/meta-data/iam/security-credentials/ follow the same rule: obtain a token first, then pass the header on each request. A script does not need a new token for every metadata path. Request one token, reuse it until its TTL expires, and then request a new one.

To inspect the full token handshake, run the PUT with headers visible:

curl -sS -i -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"

HTTP/1.1 200 OK
X-Aws-Ec2-Metadata-Token-Ttl-Seconds: 21600
Content-Length: 56
Date: Sun, 27 Sep 2026 02:58:53 GMT
Server: EC2ws
Connection: close
Content-Type: text/plain

AQAEAExampleSanitizedTokenValueForArticlePublishingOnly1234567890==

The response body is the session token. X-Aws-Ec2-Metadata-Token-Ttl-Seconds echoes the TTL AWS applied.

Token TTL and Expiration

The TTL header sets how long AWS honors a token. AWS examples commonly use 21600, the maximum six-hour TTL. You can choose any value from 1 to 21600 seconds depending on how long the process needs the token.

The token remains usable for its configured TTL and only on the EC2 instance on which it was created. After it expires, request a new token.

Long-running processes should request a new token before the current one expires or retry token creation when a metadata request indicates the token is no longer valid. If a script works initially but starts receiving 401 later, check whether it is still using an expired token.

Common curl Mistakes

If you still receive 401 after switching to IMDSv2, check these common mistakes:

If you send a normal GET request to the token endpoint instead of PUT, IMDS returns a different error:

curl -sS -i --connect-timeout 2 http://169.254.169.254/latest/api/token

HTTP/1.1 405 Not Allowed
Allow: OPTIONS, PUT
Content-Length: 0
Date: Sun, 27 Sep 2026 02:58:54 GMT
Server: EC2ws
Connection: close
Content-Type: text/plain

405 confirms the endpoint is reachable but the verb was wrong. Switch to PUT with the TTL header.

Container Hop-Limit Problems

If you are running the curl command directly on the EC2 host, you can skip this section. This issue mainly affects applications running inside containers on the instance.

Containers normally use their own virtual network environment. Reaching IMDS from inside that environment can add another network hop between the application and 169.254.169.254.

HttpPutResponseHopLimit defines how many network hops the HTTP PUT response to the token endpoint may traverse. AWS allows values from 1 to 64. With hop limit 1, a container can reach the IMDS address but the response to the IMDSv2 token PUT may not make it back through the additional network hop. The token request can time out or fail even though the same command works directly on the EC2 host. A later metadata GET may then return 401 if the script sends an empty or invalid token.

Do not increase the value simply to make a failing request work. First confirm how many network hops exist between the workload and IMDS.

Inspect the current hop limit from your workstation:

aws ec2 describe-instances \
  --region ap-south-1 \
  --instance-ids i-0123456789abcdef0 \
  --query 'Reservations[0].Instances[0].MetadataOptions.HttpPutResponseHopLimit' \
  --output text

1

Only change this setting if the application inside the container actually needs to call IMDS:

aws ec2 modify-instance-metadata-options \
  --region ap-south-1 \
  --instance-id i-0123456789abcdef0 \
  --http-put-response-hop-limit 2

Verify IMDSv1 Is Disabled

As a final check, confirm that a request without a token still returns 401, while the same request with an IMDSv2 token returns 200.

From the instance, a bare GET should remain 401:

curl -sS -o /dev/null -w "http_code=%{http_code}\n" \
  http://169.254.169.254/latest/meta-data/instance-id

http_code=401

Then confirm IMDSv2 still succeeds with a fresh token:

TOKEN=$(curl -fsS -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 60") || exit 1
curl -sS -o /dev/null -w "http_code=%{http_code}\n" \
  -H "X-aws-ec2-metadata-token: ${TOKEN}" \
  http://169.254.169.254/latest/meta-data/instance-id

http_code=200

Account and organization policies can require IMDSv2 on new instances. Update bootstrap scripts, Ansible tasks, and systemd units that still assume IMDSv1.

To disable metadata entirely, set Metadata accessible to disabled (HttpEndpoint=disabled) in the console or with modify-instance-metadata-options. That breaks any workload that still expects metadata, including many IAM role credential helpers.

Troubleshooting

Optional: Require IMDSv2 on another instance

This is not the fix for 401 on an instance that already requires tokens. Use it when you want to harden a different instance that still accepts IMDSv1:

aws ec2 modify-instance-metadata-options \
  --region ap-south-1 \
  --instance-id i-0123456789abcdef0 \
  --http-tokens required \
  --http-endpoint enabled \
  --http-put-response-hop-limit 1

New instances can set the same options at launch with --metadata-options HttpTokens=required,HttpEndpoint=enabled,HttpPutResponseHopLimit=1.

Summary

HTTP 401 from 169.254.169.254 means IMDS is reachable but the request did not include a valid IMDSv2 session token. The immediate fix is a PUT to /latest/api/token, then metadata GET requests with X-aws-ec2-metadata-token.

When Metadata version is V2 only (token required), HttpTokens is required and unauthenticated GET calls return 401 by design. Metadata is still available; clients must use the token workflow. Reuse the token until its TTL expires; request a new one when metadata calls start failing again. Common mistakes are bare IMDSv1 GETs, wrong HTTP methods on the token URL, storing HTTP error text in TOKEN, and container token failures caused by a hop limit that is too low for the extra network namespace.

As a final check, confirm that a request without a token still returns 401 while the same request with an IMDSv2 token returns 200. Only change hop limits when an application inside a container actually needs to call IMDS.

References

• Use the Instance Metadata Service to access instance metadata
• Troubleshoot instance metadata issues on my EC2 instance (AWS re:Post)
• Configure the Instance Metadata Service options
• Instance metadata and user data
• Transition to IMDSv2
• AWS CLI modify-instance-metadata-options