IMDSv2 protects EC2 instance metadata with a session token that must be requested first with a PUT call. IMDSv1 answers plain GET requests with no token. By default an instance accepts both, so to get the benefit you configure instances to require IMDSv2 and confirm your software supports it.
Why metadata matters
An EC2 instance can ask a link-local address, 169.254.169.254, for information about itself. That includes the temporary credentials of the IAM role attached to the instance. Any code that can make a request from the instance can read them, which is why a server-side request forgery bug in an app can become a credential leak.
AWS published a security blog post on defense in depth against open firewalls, reverse proxies and SSRF, which describes the thinking behind IMDSv2.
How IMDSv2 works
IMDSv2 is session oriented. A client first sends a PUT request to get a token, stating how long the token should live, from one second up to six hours. It then sends the token in a header on every GET request.
A few details from the AWS documentation matter in practice:
- The token is specific to the instance and is rejected anywhere else.
- A PUT request that carries an X-Forwarded-For header is rejected, which blocks many proxy-based tricks.
- The default response hop limit for the PUT response is 1, so the token does not travel past the instance by default.
- When tokens are required, a request with a missing or expired token gets a 401 error.
IMDSv1 is a plain request and response. If a request has no PUT or token headers, the service treats it as IMDSv1.
Requiring IMDSv2
You can set each instance so that only IMDSv2 calls succeed, which makes v1 calls fail. In the API this is the HttpTokens option set to required, changed with the modify-instance-metadata-options CLI command.
Before you flip it, check three things:
- SDK versions. AWS lists minimum versions that support IMDSv2, for example Boto3 1.12.6, AWS CLI 1.16.289 and AWS SDK for Java 2.x 2.10.21. Current SDKs all support it.
- Containers. The default hop limit of 1 can stop containers on the instance from reaching metadata. AWS notes you can raise the hop limit for that case. Decide deliberately, since a bigger hop limit lets the token travel further.
- Old scripts. Anything that runs plain curl against the metadata address will start to fail.
A safe rollout
Start with new instances, by setting the option in your launch templates. Then work through existing instances in small groups, watching for 401 errors in application logs. Keep a list of what had to stay on v1 and why, so the exceptions get fixed rather than forgotten.
Quick check
Does IMDSv2 stop SSRF completely?
No. It makes the common simple SSRF patterns much harder, because the attacker needs to send a PUT and a custom header. An application that lets attackers control methods and headers can still be abused, so fix the application bug too.
Is IMDSv2 on by default?
AWS documents that by default you can use IMDSv1, IMDSv2 or both. Requiring v2 is a setting you choose per instance.
Sources
Last reviewed: 19 October 2026.
