API Key

The LocalStack API key is a unique identifier to authenticate your LocalStack instance. You can find your API key in the LocalStack Web app. This guide demonstrates how you can use your new LocalStack licenses and go over some best practices regarding the usage, activation, and safety of your LocalStack API key.

Getting your API key

To get started, you need to have a LocalStack license. If you don’t have one, you can sign up for a free trial without any credit card required. The free trial will last 14 days, and you can use it to test all the features of LocalStack. After a free trial, you can find your API key in the LocalStack Web app in the Account → Subscriptions section.

Using your API key

LocalStack expects your API key to be present in the environment variable LOCALSTACK_API_KEY. Before starting LocalStack, define the environment variable - for example, using the following command in a MacOS or Linux environment:

$ export LOCALSTACK_API_KEY=<your-api-key>

Starting LocalStack via CLI

To start LocalStack using the LocalStack CLI, you don’t have to perform any further steps (after exporting the environment variable).

$ localstack start

LocalStack will detect the API key and properly pass it to the LocalStack container.

Starting LocalStack via Docker

To start LocalStack using Docker, you have to specify the API key using the -e flag for environment variables:

$ docker run \
  --rm -it \
  -p 4566:4566 \
  -p 4510-4559:4510-4559 \
  -e LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY:- } \
  localstack/localstack-pro

For more information about starting LocalStack, take a look at our general Getting Started guide.

Starting LocalStack via Docker-Compose

To start LocalStack using docker-compose, you have to include the LOCALSTACK_API_KEY environment variable in your docker-compose.yml file:

environment:
  - LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY- }

It sets the API key we defined before (by using the export command) into your LocalStack container, such that the key activation can take place.

Licensing-related configuration

If you want to make sure that LocalStack is only started if you can activate LocalStack Pro or Enterprise, or if you wish to suppress licensing-related error messages, take a look at our configuration guide regarding LocalStack Pro.

Checking license activation

The easiest way to check if LocalStack is activated is to query the health endpoint for a list of the running services:

$ curl localhost:4566/_localstack/health | jq

If a Pro-only service – like XRay – is running, LocalStack has started successfully. You can also check the logs of the LocalStack container to see if the activation was successful.

[...] Successfully activated API key

Otherwise, check our collected most common activation issues.

Common activation issues

Navigate to our FAQ page if your are having troubles with the LocalStack API key activation If you have any further problems concerning your API key activation, or if the steps do not help, do not hesitate to contact us.