# Configure a Gateway license

## Purpose

Install the vendor-signed Gateway license that authorizes a logical Gateway deployment and its component capacities.

## Get the identity before issuance

Create and validate the intended configuration first. The identity is configuration, not a host or hardware fingerprint:

```
/opt/particle_horizon/keystone-gateway node-id --config /opt/particle_horizon/local_config/keystone-gateway/gateway.yaml
```

Example output:

```
{"gateway_id":"gw-acme-production","replica_id":"gateway-a"}
```

For standalone, send the `gateway_id` and the one `replica_id` to the license issuer. For Active/Standby, run the command with each replica’s configuration and submit one shared `gateway_id` plus both distinct replica IDs. The same configured values can be used after a VM rebuild; copying them to an unintended clone also authorizes that clone, so protect the configuration and license. Changing either value requires a replacement license. This V1 implementation does not bind a license to a machine UUID or disk.

## Request, install, and verify

Provide the issuer with the Gateway ID, one or two replica IDs, requested expiry/term, and entitlement counts for PHOCOL and/or LMC Exporter components. When you receive `gateway-license.json`:

```
install -o keystone-gateway -g keystone-gateway -m 0600 gateway-license.json \
  /opt/particle_horizon/local_config/keystone-gateway/gateway-license.json
/opt/particle_horizon/keystone-gateway config validate --config /opt/particle_horizon/local_config/keystone-gateway/gateway.yaml
systemctl restart keystone-gateway
journalctl -u keystone-gateway -n 50 --no-pager
```

Successful startup logs `Gateway license verified`. Query authenticated `GET /v1/license` and `GET /v1/entitlements` to confirm expiry and capacity. These metadata endpoints return all entitlements in the Gateway license; a principal’s `allowed_license_type` scopes its lease operations rather than filtering these responses. Bearer authentication is restricted to lease paths and cannot query them. Gateway reads and validates the license only at startup; replacing the file requires a restart.

## What the license contains

The signed JSON document contains `schema_version: 1`, `license_type: "gateway"`, `license_id`, `customer_id`, `gateway_id`, permitted `nodes` (replica IDs), UTC `expires`, and `entitlements`. An entitlement is a non-negative concurrent capacity for a component under `phocol` or `lmc_exporter`. The signature and fingerprint protect these claims and are not returned by the API. A process starts only if schema, signature, expiry, Gateway ID, and its replica ID all validate.

Every configured authentication principal must select exactly one product type that appears in `entitlements`. The Gateway rejects startup if an `allowed_license_type` is absent from the verified license. A license containing both product types does not make one principal eligible for both; configure separate principals as described in [client authentication](https://portal.cjcit.io/knowledge-base/keystone_gateway/0.2/security/deployment-security/#configure-client-authentication).

For renewal and replacement—including capacity reductions—follow [license renewal](https://portal.cjcit.io/knowledge-base/keystone_gateway/0.2/operations/license-renewal/).