Menu
Amazon Mechanical Turk
Getting Started Guide (API Version 2014-08-15)

Setting Up Accounts and Tools

The following topics describe the tasks you need to perform before you can use Amazon Mechanical Turk.

Step 1: Sign Up for an AWS Account

To develop solutions using the Amazon Mechanical Turk web service, you must first sign up for an AWS account. An AWS account is an Amazon.com account that enables you to use services from AWS.

Note

Your AWS account must use the same credentials (email and password) that you use for your Amazon Mechanical Turk Requester account.

To sign up for an AWS account

  1. Open http://aws.amazon.com/, and then choose Create an AWS Account.

  2. Follow the online instructions.

    Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad.

Using your AWS account, you can view your AWS account activity and usage reports and manage your security credentials.

AWS Security Credentials

AWS uses access keys to help protect your data when you access AWS programmatically. An access key consists of two parts: an access key ID, which is similar to a user name, and a secret access key, which is similar to a password.

  • Sample access key ID: AKIAIOSFODNN7EXAMPLE

  • Sample secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

You use access keys to sign programmatic requests that you make to the Amazon Mechanical Turk API using, for example, one of our SDKs or our command line tools. You can use these access keys in both the sandbox and the production environment.

Note

Although you may use your AWS root credentials to access the Mechanical Turk API, we recommend that instead you create an IAM user and use those credentials instead. Please note that Mechanical Turk does not currently support the use of IAM role credentials.

To manage your AWS security credentials

  1. Sign in to the Amazon Web Services website at http://aws.amazon.com/security-credentials.

  2. Do one of the following:

    • If you signed in using your root credentials, choose Continue to Security Credentials.

    • If you signed in as an IAM user, choose Access Keys (Access Key ID and Secret Access Key).

  3. Choose Create New Access Key.

  4. In Create Access Key, choose Download Key File.

  5. The private key file (rootkey.csv) is automatically downloaded by your browser. Save the private key file in a safe place.

    Important

    This is the only chance for you to save the private key file. You will need these credentials to use the Amazon Mechanical Turk API.

Step 2: Create a Requester Account

Before you can use Amazon Mechanical Turk, you must have an Amazon Mechanical Turk Requester account.

To create and register a Requester account

  1. Go to https://requester.mturk.com.

  2. Click Create an Account.

  3. Enter your email address.

    Important

    Your Amazon Mechanical Turk Requester account must be created using the same credentials (email address and password) as the root AWS account that you created in Step 1: Sign Up for an AWS Account.

  4. Follow the prompts to complete your Requester account registration.

    When prompted, type your mailing address and accept the Amazon Mechanical Turk Participation Agreement.

Step 3: Create an IAM User

With AWS Identity and Access Management (IAM) you can securely control access to AWS services and resources for your users. Creating an IAM user allows you to use these credentials to access the Amazon Mechanical Turk API instead of using your root account credentials.

Note

You use IAM credentials only to authenticate Mechanical Turk API requests. You cannot use them to log in to the Mechanical Turk Requester website.

To create an IAM user

  1. Sign in to the Amazon Web Services website at http://aws.amazon.com/security-credentials.

  2. Choose Get Started With IAM Users.

  3. Choose Create New Users.

  4. Under Enter User Names, type names for each of your users.

  5. Make sure Generate an access key for each user is selected and choose Create.

  6. Choose Show User Security Credentials.

  7. Choose Download Credentials.

  8. Your browser automatically downloads the private key file (credentials.csv). Save the private key file in a safe place.

    Important

    This is the only chance for you to save the private key file. You will need these credentials to use the Amazon Mechanical Turk API.

To set up Amazon Mechanical Turk permissions for IAM users

  1. Read Overview of IAM Policies in the IAM User Guide.

  2. Sign in to the IAM console at https://console.aws.amazon.com/iam/home#policies.

  3. On the Policies page, choose AmazonMechanicalTurkFullAccess or AmazonMechanicalTurkReadOnly.

  4. At the top of the page, choose Policy Actions and then choose Attach.

  5. On the Attach Policy page, select the IAM user(s) that you want to set permissions for. Then choose Attach Policy to give those users permission to access the Mechanical Turk API.

What is supported?

API authentication using IAM credentials Yes
Website authentication using IAM credentials No
Action-level permissions for IAM users Yes
Resource-level permissions for IAM users No
Tag-based permissions for IAM users No
Authentication using temporary credentials (roles or groups) No
Authentication using federated user credentials No

Step 4: Download the Appropriate Amazon Mechanical Turk SDK and Tools

Amazon Mechanical Turk provides SDKs and command line tools designed to make it easier for you to build solutions leveraging Amazon Mechanical Turk. These SDKs and tools simplify using the Amazon Mechanical Turk API.

The sections below provide instructions for installing the SDKs and command line tools. You must install one of the SDKs or the command line tools to run the examples in this guide.

Install Command Line Tools

You must install and configure the command line tools correctly before you can use the command line to work through the examples in this guide.

If you use Unix (for example, Max OSX, Linux, etc), use the following procedure.

To install the Amazon Mechanical Turk command line tools for Unix users

  1. Go to Amazon Mechanical Turk Command Line Tools.

  2. Go to the [Command Line Tools Installation Directory]\ directory and open the file Overview.html.

  3. Follow the instructions in the section "Installing the command line tools" in the Overview.html file to install and configure the command line tools.

    You need your access Key ID and secret access key for this step. This can be the access key ID and secret access key for either your AWS account or for an IAM user within your AWS account.

If you use Windows, use the following procedure.

To install the Amazon Mechanical Turk command line tools for Windows Users

  1. Go to Amazon Mechanical Turk Command Line Tools and download the command line tools.

  2. Run mech-turk-setup.exe and follow the instructions.

    This setup wizard installs and configures the command line tools. You need your access key ID and secret access key for this step.

To configure an existing command line tools installation to use IAM credentials

  1. After installing the command line tools, open the mturk.properties file in the \bin directory of the CLI folder.

  2. Set the following properties to reflect your IAM credentials:

    access key=[your IAM access key]
    secret key=[your IAM secret key]

Install C# Tools

To install and configure the Amazon Mechanical Turk SDK for .NET

  1. Go to Amazon Mechanical Turk SDK for .NET and download the Amazon Mechanical Turk SDK for .NET.

  2. Open the file [SDK Installation Directory]\Overview.html.

  3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the Overview.html file.

  4. Follow the instructions in the section "Installing the Amazon Mechanical Turk SDK for .NET" of the Overview.html file to install and configure the SDK.

    You need your access key ID and secret access key for this step. This can be the access key ID and secret access key for either your AWS account or for an IAM user within your AWS account.

You must configure the SDK correctly before you can use the examples in this guide.

Install Java Tools

To install the Amazon Mechanical Turk SDK for Java

  1. Go to Amazon Mechanical Turk SDK for Java and download the SDK for Java.

  2. Open the file [SDK Installation Directory]\Overview.html.

  3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the Overview.html file.

  4. Follow the instructions in the section "Installing the SDK" of the Overview.html file to install and configure the SDK.

    You need your access key ID and secret access key for this step.

You must configure the SDK correctly before you can use the examples in this guide.

Install Perl Tools

To install the Amazon Mechanical Turk SDK for Perl

  1. Go to Amazon Mechanical Turk SDK for Perl and download the SDK for Perl.

  2. Open the file [SDK Installation Directory]\README.

  3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the README file.

  4. Follow the instructions in the "Installation" section of the README file to install and configure the SDK.

    You need your access key ID and secret access key for this step. This can be the access key ID and secret access key for either your AWS account or for an IAM user within your AWS account.

You must configure the SDK correctly before you can use the examples in this guide.

Install Ruby Tools

To install the Amazon Mechanical Turk SDK for Ruby

  1. Go to Amazon Mechanical Turk SDK for Ruby and download the Ruby libraries.

  2. Open the file [SDK Installation Directory]\README.

  3. Verify that you meet the prerequisites listed in the "Prerequisites" section of the README file.

  4. Follow the instructions in the "Installation" section of the README file to install and configure the libraries.

    You need your access key ID and secret access key for this step. This can be the access key ID and secret access key for either your AWS account or for an IAM user within your AWS account.

You must configure the SDK correctly before you can use the examples in this guide.

Configure an Existing SDK to use IAM Credentials

If you already have an SDK installed, you can set it up to use IAM credentials.

To configure an existing SDK installation to use IAM credentials

  1. After installing the SDK, open the file [SDK Installation Directory]\mturk.properties.

  2. Set the following properties to reflect your IAM credentials:

    access key=[your IAM access key]
    secret key=[your IAM secret key]

    Note

    If you are using Ruby, you need to redo step 4 in the Installation section of the README file.

Step 5: Prepay for Your HITs

The Creating a HIT tutorial uses the Amazon Mechanical Turk sandbox in which you can execute Amazon Mechanical Turk operations without having to pay Workers for working on your HITs. We recommend that you use the sandbox to test your applications before moving them to the production system. Before you use the production version of Amazon Mechanical Turk you need to prepay for the HITs you create. Otherwise, you can't post your HITs to Workers. For more information about the sandbox, see The Sandbox Testing Environment.

To post your HITs to Workers, you must have money in your Prepaid HIT Balance to prepay for all of your HITs. You can use a credit or debit card or debit card to prepay for the HITs.

For instructions on how to prepay for your HITs, go to the Requester website.

The Sandbox Testing Environment

You should test your HITs in the Amazon Mechanical Turk sandbox testing environment to make sure they work as expected before publishing your HITs in the Mechanical Turk marketplace. The sandbox provides a testing environment where you can publish and work on HITs to try them out before publishing them in the Amazon Mechanical Turk Marketplace. The sandbox consists of a Requester sandbox website and a Worker sandbox website.

You will need to create a Requester account on the Requester sandbox website, which is located at https://requestersandbox.mturk.com. You'll also need to create a Worker account on the Worker sandbox website located at https://workersandbox.mturk.com to view your sandbox created HITs as a Worker. There is no charge for using the Mechanical Turk sandbox sites.

When testing in the sandbox, test each HIT in all the major Internet browsers to make sure your HIT works the same in each browser. If you have links to pictures or videos in your HITs, make sure the links work. Also, your testing should include verifying that the format of the submitted answers is acceptable.

Creating a HIT Tutorial

The Creating a HIT tutorial in the next section takes you step-by-step through using Amazon Mechanical Turk to create a HIT. The tutorial is written procedurally so you should follow it from beginning to end. After completing the tutorial, you should have a good feel for the major tasks you can complete using Amazon Mechanical Turk.

Alternately, you can skip the Creating a HIT tutorial and jump right to the last section that provides links to code samples, application examples, forums, and other resources designed to help you learn Amazon Mechanical Turk. For more information, see Implementing Amazon Mechanical Turk.