License Management

API7 Gateway requires a valid license to operate. The license controls which features are available (e.g., API Gateway, Developer Portal) and defines the maximum number of data plane CPU cores your deployment can use, split into a production and a non-production quota.

License Properties

Each license contains the following properties:

Property	Description
Serial Number	Unique identifier for the license
Customer	Organization name
Effective Date	When the license becomes active
Expiration Date	When the license expires
Max DP Cores	Maximum total CPU cores across data plane instances in production gateway groups
Max Non-production DP Cores	Maximum total CPU cores across data plane instances in non-production gateway groups. Available in API7 Enterprise from version 3.10.5.
Feature List	Licensed features (e.g., API7 Gateway, API7 Portal)
Deployment ID	Ties the license to a specific deployment
Free Trial	Whether this is a trial license

Upload a License

Using the Dashboard

1. Log in to the API7 Dashboard.
2. If no license is active, you are prompted to upload one on login.
3. Upload the license file and click Activate.

Using the Admin API

Upload a license via the Admin API:

If you are not running locally, replace localhost with your Dashboard or Admin API host.

curl -k "https://localhost:7443/api/license" -X PUT \
  -H "Authorization: Bearer $API7_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "license": "<LICENSE_CONTENT>"
  }'

You can validate a license without applying it by adding the ?dry-run=all query parameter:

curl -k "https://localhost:7443/api/license?dry-run=all" -X PUT \
  -H "Authorization: Bearer $API7_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "license": "<LICENSE_CONTENT>"
  }'

Using a License File Path

For automated deployments (e.g., Kubernetes), you can configure the control plane to load the license from a file. The system polls the file every 5 seconds for changes.

Configure the license file path in the control plane's configuration:

Helm values

dashboard_configuration:
  license:
    file_path: "/path/to/license.txt"

This approach is useful for GitOps workflows where the license is stored as a Kubernetes Secret and mounted into the control plane pod.

Retrieve License Details

Get the current license details, including the runtime status:

curl -k "https://localhost:7443/api/license" \
  -H "Authorization: Bearer $API7_TOKEN"

The response includes the license properties and the current runtime status.

Core Quota

A license carries two independent core quotas:

Quota	Covers	License property
Production	Data plane instances in gateway groups whose environment is production	max_dp_cores
Non-production	Data plane instances in gateway groups whose environment is non_production	max_non_production_dp_cores

Every gateway group belongs to exactly one of the two, so a staging or testing gateway group does not consume production cores. See Gateway Groups for how to set the environment. Gateway groups created before version 3.10.5 count as production.

A license issued before version 3.10.5 carries no non-production quota, which reads as 0. Such a license behaves exactly as it did before as long as every gateway group stays production; to run non-production gateway groups, request a license that grants non-production cores.

How Core Usage Is Tracked

At midnight each day, the control plane measures the peak core usage from the previous day separately for each quota, and compares each against the matching licensed value.

How Gateway Worker Processes Affect Licensed Cores

The max_dp_cores property in an API7 license defines the maximum permitted DP core usage for production gateway groups. The max_non_production_dp_cores property defines the separate maximum for non-production gateway groups. Both quotas use the same accounting method.

At runtime, DP core usage is calculated from the effective number of NGINX worker processes in each gateway data plane instance. It is not calculated directly from Kubernetes apisix.resources.requests.cpu, apisix.resources.limits.cpu, or the actual CPU utilization of a pod.

The CPU configurations in the following table illustrate the license accounting method only. They are not recommended production configurations. For performance-related configuration, follow the guidance in CPU Resources and Worker Processes.

Running DP instances	nginx.workerProcesses	CPU request / limit	Counted DP core usage
One pod	1	500m / 500m	1
One pod	1	500m / 1200m	1
Two pods	1 per pod	500m / 500m per pod	1 + 1 = 2
Two pods	2 and 4, respectively	Does not affect the accounting method	2 + 4 = 6

Increasing a pod's CPU limit from 500m to 1200m therefore does not change its counted DP core usage if the effective worker count remains 1. CPU resource settings alone do not change the license usage to 0.5 or 1.2 DP cores.

License Runtime States

Each quota moves through three runtime states of its own, based on its own core usage:

State	Description	Impact
Normal	Core usage is within the licensed limit	Full functionality
DP Core Exceeded	Core usage exceeds the limit; a 7-day grace period begins	Full functionality (warning only)
Restricted	Grace period expired with cores still exceeding the limit	Write operations are blocked; read operations continue

Each quota enters and leaves these states on its own, driven only by its own usage. When one quota reaches the Restricted state:

• Blocked: Creating or updating services, routes, consumers, plugins, SSL certificates, and other configuration resources in the gateway groups that draw from that quota. Operations that are not scoped to a gateway group, such as managing users, roles, and portals, are governed by the production quota's runtime state, so they are blocked only when the production quota is restricted.
• Allowed: Everything in the gateway groups on the other quota, plus reading configurations, viewing dashboards, and uploading a new license.

To resolve the restricted state, either reduce the number of data plane cores in the affected gateway groups (e.g., by scaling down gateway replicas) or upload a license with a higher quota.

License Expiration

When a license expires:

• Read operations (viewing configurations, dashboards) continue to work.
• Write operations (creating or updating resources) are blocked.
• You can still upload a new license.

tip

Monitor your license expiration date and plan renewals in advance. If you need a license, contact API7 sales or request a trial license.

Free Trial License

A free trial license is available for evaluation purposes:

• Maximum duration: 90 days.
• The trial period starts from the deployment date.

To request a trial license, visit api7.ai/try.