AWS IAM Policy Structure Explained: JSON Elements and Examples

Simple explanation

An IAM policy is a set of instructions you hand to AWS that says: “For this identity (or this resource), allow or deny these specific actions on these specific resources, and only when these conditions are met.”

Why this matters

AWS permissions errors are notoriously confusing. An AccessDenied error might come from a missing action, a wrong resource ARN, an unmet condition, or an explicit deny overriding an allow somewhere else. You cannot debug AccessDenied errors without being able to read a policy fluently.

Writing policies matters just as much. Vague wildcard policies lead to over-permissioning and expand your blast radius. Too-narrow policies cause unexpected failures in production. Applying the principle of least privilege requires writing policies that are precise. That starts with understanding the structure.

This page builds on the concepts in IAM roles explained and managed vs customer managed policies. If you have not read those, start there.

How IAM policy structure works

The top-level JSON shape

Every IAM policy document has the same minimal skeleton:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-bucket/*"
    }
  ]
}

Two top-level fields. Version sets the policy language version. Statement is an array containing one or more permission rules. Everything else lives inside individual statement objects.

What each field means

Identity-based vs resource-based vs trust policies

AWS uses three main types of policies. The biggest structural difference is the Principal field: whether it appears, and what it means.

• Identity-based policies are attached to an IAM user, group, or role. The principal is whoever the policy is attached to, so no Principal field is needed or allowed.
• Resource-based policies are attached to a resource (S3 bucket, KMS key, SQS queue). They must include a Principal field to say who is granted access to the resource. See S3 IAM vs bucket policies for a practical comparison.
• Trust policies are attached to an IAM role and define who can assume that role. They include a Principal field naming the trusted service, account, or user.

How to read any IAM policy step by step

When you see an unfamiliar policy, or you are debugging an AccessDenied error, work through each statement with this checklist:

1. Effect: Is this statement granting or blocking access?
2. Action / NotAction: Which API calls does it cover? If it uses NotAction, what is excluded and what massive set is included?
3. Resource / NotResource: Is this scoped to a specific ARN, or is it a wildcard? If NotResource, which resources are excluded?
4. Condition: Are there extra requirements like MFA, region, IP, or tags? See IAM policy conditions explained for how to interpret these.
5. Principal (if present): Who does this statement apply to? Is it a service, a specific role, or an entire account?
6. Other policies: What other policies apply to this same principal or resource? An Allow here can be overridden by a Deny elsewhere. Check Service Control Policies, permissions boundaries, and session policies too.

For hands-on testing, the IAM Policy Simulator in the IAM console lets you pick a principal, action, and resource and shows you exactly which policy allowed or denied the request.

How to write a safe policy

Follow this workflow when creating a new customer managed policy:

1. List the exact actions. What API calls does this workload need? Check the AWS documentation for the service’s available actions. Name each one explicitly. Avoid wildcards like s3:*.
2. List the exact resources. What specific ARNs do those actions operate on? Use full ARNs where the action supports resource-level permissions.
3. Decide if a condition is needed. Should this permission only work with MFA? From a specific VPC? In a specific region? Add a Condition block if so.
4. Test with the IAM Policy Simulator before attaching the policy to a production role.

Example policies

Example 1: S3 read access to one bucket

This policy allows reading objects from a single S3 bucket and listing its contents. It uses two statements because s3:ListBucket targets the bucket ARN while s3:GetObject targets the objects inside it.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowListBucket",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::my-app-data"
    },
    {
      "Sid": "AllowReadObjects",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-app-data/*"
    }
  ]
}

This is safe because it names one bucket, uses read-only actions, and separates the bucket-level and object-level ARNs correctly. Forgetting the bucket ARN for ListBucket is a common mistake. See the common mistakes section below.

Example 2: Lambda access to one DynamoDB table + CloudWatch Logs

A Lambda function that processes orders needs to read and write items in a DynamoDB table and write logs to CloudWatch. This policy gives it exactly that and nothing more.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DynamoDBOrdersAccess",
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:UpdateItem",
        "dynamodb:Query"
      ],
      "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/orders"
    },
    {
      "Sid": "CloudWatchLogsWrite",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/order-processor:*"
    }
  ]
}

This follows the principle of least privilege. The Lambda function cannot delete items, cannot scan the full table, and can only write logs to its own log group. If this function is compromised, the blast radius is one table and one log group.

Example 3: IAM user self-managing their own credentials

This policy lets each IAM user manage their own password and access keys without giving them access to other users’ credentials. The ${aws:username} variable resolves to the name of the user making the request.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowSelfManageCredentials",
      "Effect": "Allow",
      "Action": [
        "iam:ChangePassword",
        "iam:GetUser",
        "iam:CreateAccessKey",
        "iam:DeleteAccessKey",
        "iam:ListAccessKeys",
        "iam:GetLoginProfile"
      ],
      "Resource": "arn:aws:iam::123456789012:user/${aws:username}"
    }
  ]
}

The ${aws:username} variable makes this one policy work for every IAM user in the account. Without it, you would need a separate policy per user. This variable requires “Version”: “2012-10-17”. The older 2008 policy language does not support variables.

Example 4: Trust policy on an IAM role (Principal example)

This is a trust policy attached to an IAM role. It allows the Lambda service to assume this role as its execution role. Notice the Principal field. This is what makes it a trust policy rather than an identity-based policy.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowLambdaAssume",
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

This trust policy says: “Only the Lambda service can assume this role.” The permissions policy (a separate document) attached to the same role controls what the Lambda function can actually do once it assumes the role. See IAM roles explained for the full two-policy model on roles.

When to use this

You need to understand IAM policy structure whenever you:

• Write customer managed policies, any time you create your own policies instead of using AWS managed ones.
• Review role permissions, auditing what an IAM role can and cannot do.
• Debug AccessDenied errors, tracing which statement is blocking a request and fixing it.
• Read bucket policies or trust policies, understanding who has access to a resource or who can assume a role. See S3 IAM vs bucket policies.
• Manage IAM via CLI or infrastructure as code, writing policy JSON for the AWS CLI or Terraform.