# An IAM policy is a JSON document that allows or denies actions

Facts read 16 Nov 2026. Page reviewed 16 Nov 2026.

An IAM policy is a JSON document that states which actions a principal may take on which resources, and under what conditions. AWS documentation, read on 16 Nov 2026, names nine policy types and a statement made of Version, Effect, Action, Resource and Condition elements. This page reads each element as AWS documents it.

## A policy is a list of statements that AWS joins with a logical OR

AWS defines a policy as an object that, when associated with an identity or resource, defines its permissions. AWS evaluates the policies when an IAM principal (a user or role) makes a request, and the permissions in the policies decide whether the request is allowed or denied. Most policies are stored in AWS as JSON documents.

A JSON policy document holds optional policy-wide information and one or more statements. Each statement describes a single permission. If a policy has several statements, AWS applies a logical OR across them, and if several policies apply to a request, AWS applies a logical OR across the policies as well. Splitting a policy into several statements or several policies does not change how AWS evaluates it.

AWS recommends the 2012-10-17 value for the Version element. Its policy grammar page lists two valid values, 2008-10-17 and 2012-10-17, and the workbench on this site writes the newer one into every policy it builds.

## Six elements carry the meaning of a statement

The table lists the elements of an identity-based policy statement as AWS describes them in the policy overview. Principal appears in resource-based policies and in role trust policies, not in identity-based policies, because the principal of an identity-based policy is the user or role it is attached to.

| Element | Needed | What AWS says it does |
| --- | --- | --- |
| Version | Recommended | Sets the version of the policy language; 2012-10-17 is the latest. |
| Statement | Yes | Container for one or more statements. |
| Sid | Optional | A statement ID that tells your statements apart. |
| Effect | Yes | Allow or Deny. |
| Principal | Resource-based policies only | The account, user, role or federated principal the statement applies to. |
| Action | Yes (or NotAction) | The list of actions the policy allows or denies. |
| Resource | Required in identity-based policies | The list of resources the actions apply to. |
| Condition | Optional | The circumstances under which the statement is in effect. |

## Action names are not case sensitive, and two element pairs exclude each other

AWS states that the prefix and the action name in an Action value are case insensitive: iam:ListAccessKeys is the same as IAM:listaccesskeys. A policy that spells an action in a different case is therefore not wrong on that account, although a checker that compares text will treat the two spellings as different strings. The workbench compares action names without regard to case for this reason.

AWS also states that some elements exclude each other. A statement cannot use both Action and NotAction, both Principal and NotPrincipal, or both Resource and NotResource. The wildcards page covers NotAction, which reverses the meaning of a statement and is the element most often misread.

## A three-statement example shows how Resource "*" can still be narrow

AWS gives an example policy with three statements. The first, with the Sid FirstStatement, lets a user change their own password and uses Resource "*". AWS explains that the ChangePassword operation affects only the password of the user who makes the request, so the star does not widen it.

The second statement lets the user list the S3 buckets in their own account, again with Resource "*". AWS notes that policies do not grant access to resources in other accounts, so the user can list only buckets in their own account. The third statement allows listing and reading objects in one named bucket, but only when the user signed in with multi-factor authentication, through a Condition element.

The lesson for reading a policy is that a star in Resource does not always mean broad access. It depends on the action. The workbench shows the number of actions each wildcard expands to and the access level of each action, so a star on a list action reads differently from a star on a write action. See [the wildcards page](/iam-wildcards/) and [the access levels page](/iam-access-levels/).

## Nine policy types sit around the JSON identity policy

AWS supports nine types of policies: identity-based policies, resource-based policies, VPC endpoint policies, permissions boundaries, Organizations service control policies, Organizations resource control policies, access control lists, Resource Access Manager shares and session policies. Only access control lists do not use the JSON policy structure. The next page, [AWS IAM policy types](/aws-iam-policy/), says when each applies.

The workbench on this site reads and checks five of the nine: identity policies, service control policies, resource control policies, permissions boundaries and role trust policies. It reads a policy you paste and reports what it grants. It does not evaluate the policy against an AWS account, so it does not say whether a particular request would be allowed. [The simulator page](/iam-policy-simulator/) explains the tool AWS provides for that.

## Related pages

- [AWS IAM Policy Types and When Each One Applies](/aws-iam-policy/)
- [IAM Policy Simulator: What AWS Provides](/iam-policy-simulator/)
- [IAM Access Analyzer: What It Checks and Finds](/iam-access-analyzer/)
- [All of them](/guides/)

## Sources

- Policies and permissions in AWS Identity and Access Management: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html (read 16 Nov 2026)
- IAM JSON policy element reference: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html (read 16 Nov 2026)
- Grammar of the IAM JSON policy language: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_grammar.html (read 16 Nov 2026)
- IAM JSON policy elements: Action: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_action.html (read 16 Nov 2026)

Last reviewed 16 Nov 2026. Canonical: https://iampolicygenerator.com/iam-policy/

This site is not affiliated with Amazon Web Services. AWS service and product names are used only to describe AWS services.
