Auth Token

What is an Auth Token?

An Auth Token is a mandatory credential required to start the LocalStack container and activate licensed features. It links your running LocalStack instance to your workspace license and unlocks the services and capabilities available to your account.

You can manage Auth Tokens from the Auth Tokens page in the LocalStack Web Application.

Credential security

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

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.

Configure your token

Authentication requirements vary based on your chosen execution method.

lstk

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

LocalStack CLI

If you use the LocalStack CLI, set your token with the auth command. This stores the token in your local configuration.

localstack auth set-token <YOUR_AUTH_TOKEN>
localstack start

Docker and Docker Compose

For direct container execution, inject the token as an environment variable. For complete startup examples, see the Docker Compose and Docker CLI installation options.

Docker CLI:

-e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN}

Docker Compose:

environment:
  - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN}

CI environments

CI environments should use a dedicated CI Auth Token stored in your CI provider’s secret manager. For complete examples, see the CI/CD guide.

Verify activation

Verify the activation status by querying the LocalStack info endpoint:

macOS/Linux

curl http://localhost:4566/_localstack/info | jq

Windows

Invoke-WebRequest -Uri http://localhost:4566/_localstack/info | ConvertFrom-Json

Output

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

The edition field should be pro, and is_license_activated should be true.

License assignment

An Auth Token can only activate licensed features if a license is assigned to the associated user or workspace.

1. Navigate to the Users & Licenses page.
2. Identify the target user in Workspace Members.
3. Select the appropriate Member Role.
4. Save the configuration to activate the license for that identity.

Note

LocalStack cannot activate licensed features unless the token belongs to a user or workspace with an assigned license.

Rotate a token

Rotate an Auth Token if it has been exposed, shared accidentally, or stored in a place where it should not be. Go to the Auth Tokens page and select the reset option for the affected token.

After rotation, update every local shell, container configuration, or CI secret that used the old token.

Troubleshooting

LocalStack requires successful license activation during startup. If activation fails, LocalStack exits and displays an error message:

===============================================
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`.

Activation may fail for several reasons, and the most common ones are listed below.

Missing credentials

You need to provide 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.

Next steps

After configuring your Auth Token, continue to the Local Development guide to start LocalStack and deploy a local serverless API.