API access control

You can use the AWS Marketplace Catalog API to manage a seller product in AWS Marketplace or an experience in a private marketplace. However, first make sure your user or role can access the API functionality that you want to call.

Use AWS Identity and Access Management (IAM) to create users and roles and assign policies that grant limited permissions to end users. The policies define the actions that the user or role can take on your resources through the AWS Marketplace Catalog API.

For example, you can define roles such as engineering, marketing, and pricing. Then, you can add a user in your organization to the engineering role. In that role, they might be granted permissions to initiate a change request to publish a new version of your seller product. However, the engineering role doesn't allow the user to list all change sets.

You can use AWS managed policies, or you can create your own IAM policies to have more granular control than what's available in AWS managed policies. For details about these approaches, see the following topics.

Allowing actions with AWS managed policies

You can use policies that are managed by AWS to grant permissions to your user or role.

To work with products that you sell on AWS Marketplace, you can use the AWSMarketplaceSellerFullAccess IAM managed policy, which has full access to the AWS Marketplace Catalog API in addition to its other permissions. You can grant read-only access for the Catalog API with the AWSMarketplaceSellerProductsReadOnly policy. For more information, see Controlling access to AWS Marketplace Management Portal, Policies and permissions for AWS Marketplace sellers, and AWS managed policies for AWS Marketplace sellers in the AWS Marketplace Seller Guide.

To manage a private marketplace, you can use the AWSPrivateMarketplaceAdminFullAccess IAM managed policy, which has full access to create and edit the private marketplace for your account or AWS organization. For more information, see Controlling access to AWS Marketplace subscriptions, Creating a private marketplace administrator, and AWS managed policies for AWS Marketplace buyers in the AWS Marketplace Buyer Guide.

Alternatively, you can create your own IAM policies to have more granular control than is available in AWS managed policies. Use the following topics to create your own IAM policies.

Allowing actions on all resources

Resources are objects that the actions can act upon. Not every resource type can be specified with every action. Some resource types work with only certain actions. For more information, see Actions, resources, and condition keys for the AWS Marketplace Catalog in the Service Authorization Reference.

There are two resource types in the Catalog API:

To allow a user or role the permission to make changes to all entities in an AWS account, you can add the following IAM policy. With this policy, the user or role can use the StartChangeSet action on all resources ("*").

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:StartChangeSet"
      ],
      "Resource": "*"
    }
  ]
}

For information about all actions available for the Catalog API, see Actions, resources, and condition keys for AWS Marketplace Catalog in the Service Authorization Reference.

Allowing actions on specific resources

Instead of allowing changes to all resources, you can use resource-level permissions to allow changes to specific resources.

For example, you can allow changes to a specific seller product in the AWS account instead of to all seller products. You do this by specifying the Amazon Resource Name (ARN) of the seller product in the Resource of the IAM policy.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:StartChangeSet"
      ],
      "Resource": [
        "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example1-abcd-1234-5ef6-7890abcdef12",
        "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/*"
      ]
    }
  ]
}

For another example, you can allow changes to a specific experience in a private marketplace instead of to all experiences. You do this by specifying the ARN of the experience in the Resource of the IAM policy.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:StartChangeSet"
      ],
      "Resource": [
        "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/Experience/exp-example12345",
        "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/*"
      ]
    }
  ]
}

Allowing actions with specific ChangeType condition key

The Catalog API action StartChangeSet has several different change types. You can allow access to only specific change types.

For example, you might only want to allow changes to the metadata of the seller product, such as the product title, and not allow adding new product versions. In this example, the change type UpdateInformation allows changing the metadata of a seller product, including the title. For more information about the different change types, see Working with seller products and Working with a private marketplace in the AWS Marketplace Catalog API Reference.

To limit the action to one or multiple change types, specify the ChangeType in the condition keys. In the following example IAM policy, the condition operator StringEquals specifies that the action is only allowed if the ChangeType matches UpdateInformation. For more information about condition keys, see Condition operators in the AWS Identity and Access Management User Guide.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:StartChangeSet"
      ],
      "Resource": [
        "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/AmiProduct/example1-abcd-1234-5ef6-7890abcdef12",
        "arn:aws:aws-marketplace:us-east-1:123456789012:AWSMarketplace/ChangeSet/*"
      ],
      "Condition": {
        "StringEquals": {
          "catalog:ChangeType": "UpdateInformation"
        }
      }
    }
  ]
}

Allowing actions with specific aws:ResourceTag condition key

You can allow actions on a group of entities without having to keep updating the policy and specifying a possibly growing list of entity ARNs. You can do this with resource tagging. Adding tags to resources allows you to control access to those resources based on their tags. For example, you might want to allow describing a group of seller products without specifying individual ARNs for each seller product.

For example, the following IAM policy allows the DescribeEntity action on any entity resource ("*") that has a tag key of product-team and tag value of team-xyz.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:DescribeEntity"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/product-team": "team-xyz"
        }
      }
    }
  ]
}

You can also allow describing and canceling change sets that were created with specific tags.

For example, the following IAM policy allows the DescribeChangeSet and CancelChangeSet actions on any change set resource ("*") that has a tag key of product-team and tag value of team-xyz.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:DescribeChangeSet",
        "aws-marketplace:CancelChangeSet"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/product-team": "team-xyz"
        }
      }
    }
  ]
}

Also, you can allow starting change sets on entities only when those entities have specific tags. For example, you can allow changes to seller products with specific tags.

For example, the following IAM policy allows the StartChangeSet action on any entity resource ("*") that has a tag key of product-team and tag value of team-xyz. In addition, the TagResource action is required so that when the change set is created, it’s tagged with the same tag key and value.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:StartChangeSet",
        "aws-marketplace:TagResource"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/product-team": "team-xyz"
        }
      }
    }
  ]
}

Creating a custom IAM role

Customers who want to use a Resale Authorization ChangeType or a CPPO ChangeType need to create a custom AWS Identity and Access Management (IAM) role. This will support the creation of the Resale Authorization product lifecycle.

Managing tags on resources

You can add, list, and remove tags from existing entities or change sets.

Add tags to resources

To add tags to an entity or change set, use the TagResource API action.

Request

POST /TagResource HTTP/1.1
Content-type: application/json

{
  "Catalog": "AWSMarketplace",
  "ResourceArn": "string",
  "Tags": [
    {
      "Key": "string",
      "Value": "string"
    }
    ...
  ]
}

Request parameters include:

Response

{}

Remove tags from resources

To remove a tag or list of tags from an entity or change set, use the UntagResource API action.

Request

POST /UntagResource HTTP/1.1
Content-type: application/json

{
  "Catalog": "AWSMarketplace",
  "ResourceArn": "string",
  "TagKeys": [
    "string"
    ...
  ]
}

Request parameters include:

Response

{}

List all tags on a resource

To list all tags that have been added to and not yet removed from a change set or entity, use the ListTagsForResource API action.

Request

POST /ListTagsForResource HTTP/1.1
Content-type: application/json

{
  "Catalog": "AWSMarketplace",
  "ResourceArn": "string"
}

Request parameters include:

Response

{
  "ResourceArn": "string",
  "Tags": [
    {
      "Key": "string",
      "Value": "string"
    }
    ...
  ]
}

Managing tags when requesting changes to resources

You can add tags when entities or change sets are created.

Example: Adding tags to a change set when creating a change set

The following is an example of a StartChangeSet request that updates the product metadata for a seller product. This request adds a tag to the change set that's created with this request by including the tag in the ChangeSetTags property.

POST /StartChangeSet HTTP/1.1
Content-type: application/json

{
  "Catalog": "AWSMarketplace",
  "ChangeSet": [ 
    { 
      "ChangeType":"UpdateInformation",
      "Entity": {
        "Identifier":"example1-abcd-1234-5ef6-7890abcdef12",
        "Type":"AmiProduct@1.0"
      },
      "Details": "{\"ProductTitle\":\"My updated title\"}"
    }
  ],
  "ChangeSetTags": [
    {
      "Key": "product-team",
      "Value": "team-xyz"
    }
  ]
}

For more information about managing seller products, see Working with seller products in the AWS Marketplace Catalog API Reference.

Example: Adding tags to an entity and change set during creation

The following is an example of a StartChangeSet request that creates a private marketplace experience entity. The request adds tags to both the entity resource and change set resource created with this request by including the tags in the EntityTags and ChangeSetTags properties. With these tags, the permission policy of a user or role can be specified to only allow describing or canceling the change set this request creates or only allow creating further change sets on the entity this request creates. For more information, see Granting permission to create entities and change sets only with tags.

POST /StartChangeSet HTTP/1.1
Content-type: application/json

{
  "Catalog": "AWSMarketplace",
  "ChangeSet": [ 
    { 
      "ChangeType": "CreateExperience",
      "Entity": { 
        "Type": "Experience@1.0"
      },
      "Details": "{\"Name\": \"ExamplePrivateMarketplace\"}",
      "EntityTags": [
        {
          "Key": "product-team",
          "Value": "team-xyz"
        }
      ]
    }
  ],
  "ChangeSetTags": [
    {
      "Key": "product-team",
      "Value": "team-xyz"
    }
  ]
}

For more information about managing a private marketplace, see Working with a private marketplace in the AWS Marketplace Catalog API Reference.

Granting permission to manage tags on resources

To allow a user or role to add, remove, and list tags on all entities or change sets, they need the following IAM policy.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:TagResource",
        "aws-marketplace:UntagResource",
        "aws-marketplace:ListTagsForResource"
      ],
      "Resource": "*"
    }
  ]
}

Granting permission to manage tags on resources only when those resources have specific tags

You can allow a user or role to add, remove, and list tags on entities or change sets that have specific tags. The following IAM policy allows those actions on any entity resource ("*") that has a tag key of product-team and tag value of team-xyz.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:TagResource",
        "aws-marketplace:UntagResource",
        "aws-marketplace:ListTagsForResource"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/product-team": "team-xyz"
        }
      }
    }
  ]
}

Granting permission to create entities and change sets only with tags

You can enforce tagging when entities or change sets are created. Add the following policy to allow the StartChangeSet and the TagResource actions, with a condition specifying the tag key matches product-team and the tag value matches team-xyz. This policy condition must match both the tag on the newly created entity and the tag on the newly created change set resulting from the creation request. For an example of tagging an entity on creation, see Example: Adding tags to an entity and change set during creation.

For existing entities, this policy also enforces tagging change sets when requesting changes to those entities. This also requires that the existing entity has this existing tag. This is because the policy condition must match both the tag on the existing entity and the newly created change set resulting from the change request. For an example of adding tags to change requests, see Example: Adding tags to a change set when creating a change set.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:StartChangeSet",
        "aws-marketplace:TagResource"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/product-team": "team-xyz"
        }
      }
    }
  ]
}