License Sources

A license source is a place your software looks for its license: a connection to Axoniq Platform, Axon Server, an environment variable, or a file. Axoniq Framework and Axon Server support different sources and read them in different ways, so they are described separately.

The environment variable AXONIQ_LICENSE means something different in each product. In Axoniq Framework it contains the license itself. In Axon Server it contains the path to a license file.

Axoniq Framework

This describes Axoniq Framework 5.3.2 and later.

Sources

Axoniq Framework checks up to four sources, in this order of priority:

Priority Source Used when

1

Axoniq Platform

The application connects to Axoniq Platform

2

Axon Server

The application connects to Axon Server 2026.0 or later

3

AXONIQ_LICENSE environment variable

The variable is set

4

License file

The file exists when the application starts
Axoniq Platform

Configure the connection with the axoniq.platform.credentials property; see Axon Framework Client. The application requests its license when it connects, and Axoniq Platform sends a new one whenever the license is renewed or your plan changes. When the connection drops, the application keeps using the license it has until that license expires.

Axon Server

When the application connects to Axon Server 2026.0 or later, it asks Axon Server for the cluster’s license every minute. This lets applications that cannot reach Axoniq Platform themselves use the license of the Axon Server cluster they connect to. Older Axon Server versions do not offer their license; the application logs that Axon Server should be upgraded and ignores this source.

AXONIQ_LICENSE environment variable

Contains the license content, either as is or base64-encoded. Base64 is easier to pass through container platforms and secret stores. The variable is read once, when the application starts.

License file

The application looks for the file in this order:

  1. the path in the JVM system property axoniq.license.file, for example java -Daxoniq.license.file=/etc/myapp/axoniq.license -jar my-application.jar;

  2. the path in the environment variable AXONIQ_LICENSE_FILE;

  3. axoniq.license in the working directory.

    The file must exist when the application starts. Changes to it are picked up while the application runs, so you can replace an expiring license without a restart.

    axoniq.license.file is a JVM system property, not a Spring property. Setting it in application.properties or application.yml has no effect.

How the license is chosen

When the application starts, it waits until every configured source has reported whether it has a license. It then uses the license of the source with the highest priority that has one.

It moves on to the next source when a source:

  • cannot be reached, for example because Axoniq Platform or Axon Server is down;

  • has no license, for example because the file does not exist or the variable is empty;

  • rejects the application, for example because its access token is invalid or the plan’s application limit is reached;

  • returns something that is not a license.

When a source with a higher priority recovers, the application switches back to it.

Choosing a source is based on availability only. The application does not compare licenses, and does not look at their signature or expiry date to decide which one to use.

The chosen license is validated afterwards. If it is not valid, the application does not try another source: it stops. This happens when the chosen license:

  • has an invalid signature, for example because it was edited;

  • is past the end of its grace period;

  • may only be used with a connection to Axoniq Platform, but was read from a file or environment variable;

  • does not cover all the commercial modules the application uses.

So an expired license file stops an application whenever a higher-priority source is unavailable, even if another source holds a valid license. Keep the license files and variables you configure up to date, or remove them once you no longer need them.

Some examples, for an application that connects to Axoniq Platform and also has a license file:

Situation Result

Axoniq Platform is reachable

The license from Axoniq Platform is used. The file is ignored.

Axoniq Platform is not reachable when the application starts

The file is used. When Axoniq Platform becomes reachable, the application switches to its license.

The connection drops while the application runs

The application keeps the license from Axoniq Platform until it expires.

Axoniq Platform is not reachable when the application starts, and the file holds an expired license

The application stops, although Axoniq Platform would have provided a valid license once reachable.

What the application logs

All license messages are prefixed with [AXONIQ].

Message Meaning

Using the License received from <source>

The application uses the license from this source.

<source> became unavailable, falling back to <source> for License

The preferred source stopped providing a license; a lower-priority source is used.

<source> became available and has higher priority, switching from <source> for License

A preferred source recovered.

License validated and applied - Workspace: '…', Environment: '…'

The license is valid. The message links to the environment in Axoniq Platform.

A valid license must be provided by one of the license sources … within 24 hours, or the JVM will shut down.

No source has provided a license yet. See Rotation and Expiry.

License validation failed, could not apply received license. Shutting down the JVM.

The chosen license has an invalid signature or is malformed.

Not all detected addons are covered by your license. Shutting down the JVM.

The application uses a commercial module that the license does not include.

Axon Server

Axon Server reads its license from Axoniq Platform or from a file.

From Axoniq Platform

Configure the connection with axoniq.platform.authentication; see Axon Server. Axoniq Platform sends the license to every node when it connects, and again whenever the license is renewed or your plan changes. Each node receives the license version it supports.

A license received from Axoniq Platform takes precedence over a license file. Axon Server also saves it as its license file, unless the license may only be used with a connection to Axoniq Platform.

From a file

Axon Server looks for the file in this order:

  1. the path in the JVM system property license, or in the environment variable AXONIQ_LICENSE, if a file exists at that path;

  2. axoniq.license in the directory set by axoniq.axonserver.enterprise.license-directory, which is the working directory by default.

For example, in axonserver.properties:

axoniq.axonserver.enterprise.license-directory=/etc/axonserver

Or, when running Axon Server in a container:

docker run \
    -v ./axoniq.license:/axonserver/config/axoniq.license:ro \
    -e AXONIQ_LICENSE=/axonserver/config/axoniq.license \
    docker.axoniq.io/axoniq/axonserver

Axon Server reads the file again at least every hour, so a replaced file takes effect without a restart.

A license file used this way must allow running without a connection to Axoniq Platform. See Running Without a Platform Connection.