Skip to main content
We recommend getting started in the playground environment. The playground lets you test your integration safely, and playground keys can call every endpoint. To create one, choose Playground key in step 2. When you’re ready to go live, follow this guide again to create a production key.
1

Open the API keys page

Navigate to the API section within your account dashboard. Click the “Create new API key” button to generate a new API key.

The API keys page is empty when you first open it.

2

Choose the environment

You now need to choose the environment to create the API key in. For this guide we will use the production environment.

The environment modal is displayed when you click the 'Create new API key' button.

3

Give the API key a name

You should give the API key a name that will help you identify it. This is helpful when managing multiple API keys. It’s best practice to generate new keys for each use case and revoke them when they are no longer needed.

When creating a new API key, you will be asked to give it a name.

4

Choose the scopes

Scopes control which endpoints a production API key can call. Select only the scopes your integration needs. For example, a key that only places orders needs just create:order.
Playground keys don’t have scopes and can call every endpoint. If you’re creating a playground key, there is no scopes step.

Select the scopes the API key needs.

Giving a key the minimum scopes it needs limits what someone could do with it if it were ever exposed. Use separate keys for separate use cases, such as one key for placing orders and another for reporting. See scopes for the scope each endpoint requires.
5

Copy the API key

After the key is created it will be displayed to you only once. You should copy the key and store it securely. If you loose the key you will need to revoke it and generate a new one.

The API key is displayed to you only once.

Securing your API keyIt is your responsibility to keep your API keys safe and secure. Anyone holding your key will be able to make requests to the API on your behalf. Review our security best practices for information on how to keep your API keys secure.

​
The API keys page

Once you have created an API key you can view it on the API keys page. You can also revoke any keys from this page. You can read more in the authentication guide.

The API keys page lists your keys and the scopes of each one.

​
Using your API key

​
The API key header

When making requests to the API you will need to include the API key in the request headers. It must be included in the X-Api-Key header for all requests.

​
Testing your API key

You can verify that your API key is working correctly by making a request to the ping endpoint. This is a simple health check endpoint that requires authentication but doesn’t perform any other operations.
If your API key is valid, you’ll receive this response:
If you receive an error, check that:
  • You’ve copied the entire API key correctly
  • You’re using the correct environment URL (playground or production)
  • The API key hasn’t been revoked
  • The API key has the read:ping scope (a missing scope returns a 403)

Next step: Your first order

Now that you have your API key, let’s put it to use by making your first order. You’ll learn about the different ordering modes available and choose the one that best suits your needs. The first order guide uses the playground environment, so you’ll need a playground key. Create one by choosing Playground key in step 2. Playground keys don’t have scopes, so there is no scopes step.