Auth Token

The Auth Token is a mandatory credential required to pull the localstack-pro image and activate service entitlements. It links your local instance to your workspace license and enables access to the full suite of emulated AWS services.

Token Types

Token Type	Scope	Use Case
Developer Token	Individual	Local development workstations. Managed per user.
CI Auth Token	Workspace	Automated pipelines and shared runners. Managed by workspace admins.

Manage both token types on the Auth Tokens page in the LocalStack Web Application.

Credential Security

Auth Tokens provide full access to your license and workspace. Do not commit tokens to version control. If a token is exposed, rotate it immediately via the Web Application to invalidate existing sessions.

Configuration Methods

Authentication requirements vary based on your chosen execution method.

1. lstk (Automated)

The lstk CLI automates the authentication lifecycle. On initial execution, it triggers a browser-based OAuth flow and stores the resulting token in your system keyring. No manual environment variable configuration is required.

lstk start

2. LocalStack CLI

If you use the standard CLI, set your token using the auth command. This persists the credential in your local configuration.

3. Docker & Docker Compose

For direct container execution, inject the token as an environment variable.

Docker CLI:

docker run \
  --rm -it \
  -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} \
  localstack/localstack-pro

Docker Compose:

services:
  localstack:
    image: localstack/localstack-pro
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN}

License Assignment

An Auth Token is only valid if a license is assigned to your user identity or workspace.

Assignment Workflow:

1. Navigate to the Users & Licenses page.
2. Identify the target user in Workspace Members.
3. Select the appropriate Member Role (Admins receive full permissions by default).
4. Save the configuration to activate the license for that identity.

Note

An active Auth Token will fail to initialize the container if a valid license has not been assigned to the associated user.

Activation Verification

Verify the activation status by querying the LocalStack info endpoint:

Successful Activation Output:

{
  "edition": "pro",
  "is_license_activated": true
}

Next steps

You have successfully completed the Getting Started sequence! Proceed to the FAQ for troubleshooting common scenarios, or explore our supported local AWS services to begin building.

Troubleshooting

While using Auth Tokens, LocalStack demands a successful license activation for startup. If the activation of the license is unsuccessful, LocalStack will exit and display error messages.

===============================================
License activation failed! 🔑❌

Reason: The credentials defined in your environment are invalid. Please make sure to either set the LOCALSTACK_AUTH_TOKEN variable to a valid auth token, or the LOCALSTACK_API_KEY variable to a valid LocalStack API key. You can find your Auth Token or API key in the LocalStack web app https://app.localstack.cloud.

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

- Please check that your credentials are set up correctly and that you have an active license.
  You can find your credentials in our webapp at https://app.localstack.cloud.
- If you want to continue using LocalStack without pro features you can set `ACTIVATE_PRO=0`.

The key activation in LocalStack may fail for several reasons, and the most common ones are listed below in this section.

Missing Credentials

You need to provide either an Auth Token to start the LocalStack for AWS image successfully. You can find your Auth Token on the Auth Tokens page in the LocalStack Web Application.

If you are using the localstack CLI, you can set the LOCALSTACK_AUTH_TOKEN environment variable to your Auth Token or use the following command to set it up:

localstack auth set-token <YOUR_AUTH_TOKEN>

Invalid License

The issue may occur if there is no valid license linked to your account due to expiration or if the license has not been assigned. You can check your license status in the LocalStack Web Application on the My License page.

License Server Unreachable

LocalStack initiates offline activation when the license server is unreachable, requiring re-activation every 24 hours. Log output may indicate issues with your machine resolving the LocalStack API domain, which can be verified using a tool like dig:

dig api.localstack.cloud

If the result shows a status other than status: NOERROR, your machine is unable to resolve this domain. Certain corporate DNS servers may filter requests to specific domains. Kindly reach out to your network administrator to safelist localstack.cloud domain.

If you have any further problems concerning your license activation, or if the steps do not help, don’t hesitate to contact us.