Tutorial: How to use IAM to control API access to your MTurk Account

Amazon Mechanical Turk (MTurk) Requester customers can use the MTurk Requester API to write code to submit tasks and retrieve results programmatically using an Amazon Web Services (AWS) account.

One of the features of the API is support for AWS Identity and Access Management (IAM). IAM lets you limit the access permissions of the AWS account you use with MTurk. This allows you to improve the security of your API code, especially when using MTurk at scale. In this blog post we will show you how to configure IAM.

To begin, create an AWS account here. Once you have created an AWS account, you will be signed in to the AWS console like below.

Now it is time to set up IAM. You can go to the IAM section by navigating to the IAM console or by typing in “IAM” into the search bar on the AWS Console page.

IAM allows you to create “Users”. You can then give an IAM user account permissions to access specific AWS services including the MTurk Requester API. Start by creating a new IAM user. Go to the “Users” section on the left and then click on “Add user” in the right hand panel.

In the following screen you will be able to specify your IAM user settings like below:

Select “Programmatic access” and leave the “AWS Management Console access” checkbox unchecked. Then click on “Next: Permissions”.

Next you can specify what permissions you want for this IAM user. In this case, you want to give the account access to the MTurk Requester API.

Click on the “Attach existing policies directly” button and then search for and select “AmazonMechanicalTurkFullAccess”. This policy gives the account access to the MTurk Requester API and no other AWS services:

Click on “Next:Review” and then click on “Create user”. You will now see your IAM user created with two important pieces of information: an Access key ID and a Secret access key (which will be hidden by default).

It is important to record both these values in a secure place. These are the keys that you will use when making requests to the MTurk Requester API from your code. For security reasons, once you leave this screen you will not be able to retrieve the Secret access key again for this Access key ID. However, you can create additional access keys for your IAM user in the future.

Fine-grained permissions control
The IAM user you just created has the “AmazonMechanicalTurkFullAccess” permissions policy attached to it. This is a standard policy that allows the account to call any of the operations the MTurk Requester API offers.

However, it is also possible to create your own custom policies to configure IAM accounts so that they can only access some MTurk operations and not others.

For example, imagine an academic lab where multiple researchers and students need access to the lab’s MTurk account. As a best practice, you might want to give all researchers and students IAM accounts that can only retrieve results and then give a smaller group permissions to publish new tasks, approve and pay workers and send bonuses etc. This would improve your ability to audit access to your shared resource and limit the impact if any accounts get compromised.

Start by going back to the IAM console and creating your own policy. Click on the “Policies” link on the left and then click on the “Create Policy” link the top of the right hand panel:

Click on the “Create Your Own Policy” option and create a new policy as below:

You can copy and paste in the example policy from below:

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Action": [
            "mechanicalturk:SearchHITs",
            "mechanicalturk:GetReviewableHITs",
            "mechanicalturk:GetHIT",
            "mechanicalturk:GetAssignmentsForHIT",
            "mechanicalturk:GetAssignment"
         ],
         "Resource": ["*"]
      }
   ]
}

As you can see above, this policy allows the IAM user to only access the SearchHITs, GetReviewableHITs, GetHIT, GetAssignmentsForHIT and GetAssignment operations.

You can also specify permissions you want to specifically deny using a combination of allow and deny statements. For example:

{
   "Version": "2012-10-17",
   "Statement": [
       {
         "Effect": "Allow",
         "Action": [
            "mechanicalturk:*"
          ],
         "Resource": [
            "*"
          ]
       },
       {
         "Effect": "Deny",
         "Action": [
            "mechanicalturk:GrantBonus"
          ],
         "Resource": ["*"]
        }
    ]
}

This policy creates an IAM user that can call any operation in the MTurk Requester API except the ability to give bonuses to Workers.

Once you’ve created the policy, you will now see it show up in your list of IAM policies and you can attach it to any IAM user just as we walked through previously.

You can learn more about using IAM from the IAM User Guide.

If you have any questions, please post a question to our MTurk forums. To become a Requester, sign up here. Want to contribute as a Worker customer? Get started here.