API Key

The LocalStack API key is a unique identifier to activate your LocalStack license needed to start LocalStack Pro. 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 Settings → API Keys section.

Starting LocalStack via CLI

LocalStack expects your API key to be present in the environment variable LOCALSTACK_API_KEY. You can define the LOCALSTACK_API_KEY environment variable before or while starting LocalStack using the localstack CLI.

• macOS/Linux
• Windows

export LOCALSTACK_API_KEY=<YOUR_API_KEY>
localstack start -d

$env:LOCALSTACK_API_KEY=<YOUR_API_KEY> localstack start -d

The localstack CLI 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 with Docker, take a look at our Docker installation 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- }

You can set the API key manually, or you can use the export command to set the API key in your current shell session. The API key will be passed 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

Since LocalStack v2.0.0, the image localstack/localstack-pro requires a successful key activation to start. If the key activation fails, LocalStack will quit with an error messages that may look something like this:

===============================================
API key activation failed! 🔑❌

The API key you provided in the `LOCALSTACK_API_KEY` environment variable '"foo..."(6)' could not beactivated against our licensing server. Server message: Unable to verify API key.

Due to this error, Localstack has quit. LocalStack pro features can only be used with a valid license.

- Please check that your API key is set up correctly and that you are using the correct key.
  You can find your API key in our webapp at https://app.localstack.cloud.
- If you want to continue using LocalStack without pro features you can set `ACTIVATE_PRO=0`.

There are several reasons a key activation can fail:

• Missing credentials: Using localstack/localstack-pro requires per default to have an API key set.
• Invalid key: there is no valid license associated with the key, for example because the license has expired.
• License server cannot be reached: LocalStack will try to perform an offline license activation if the license server cannot be reached, but will require a re-activation every 24 hours.

If you are using the localstack/localstack-pro image, but cannot activate your license key, we recommend falling back to the community version localstack/localstack. If that is not an option, you can set ACTIVATE_PRO=0 which will attempt to start LocalStack without pro features.

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.