Managing Customer License Fields

This topic describes how to manage both built-in and custom license fields for customer records in the Replicated Vendor Portal.

Overview

The Replicated Vendor Portal allows administrators to manage both built-in and custom license fields for customer records. When a customer installs an application distributed with Replicated, the values for each built-in and custom field in their license can be accessed using the Replicated SDK in-cluster API license endpoints. Applications installed with a Replicated installer (KOTS, kURL, Embedded Cluster) can also access license fields using the Replicated KOTS LicenseFieldValue template function.

Common Use Cases

Custom license fields allow you to add business-specific data to customer licenses:

• Capacity limits: Control usage with fields like max_users, seats, storage_gb, api_calls_per_month
• Feature tiers: Use tier (basic/premium/enterprise) or support_level (standard/priority) to enable different features
• Configuration: Store api_endpoint, region, data_center, or environment settings
• Credentials: Securely include api_key, auth_token, or encryption_key (use Password type to mask in UI)
• Business logic: Track contract_type, renewal_date, or account_manager for reporting and workflows

Built-In License Fields

Built-in fields come standard with all customer records in the Vendor Portal. The license associated with each customer record includes several built-in fields, such as customer properties (customer name, customer email, and the Vendor Portal channel where the customer is assigned), the license expiration date, and the Replicated features that are enabled for the customer (such as the supported install types or Admin Console features).

Administrators can:

• Set initial values that populate the customer creation form

  note

  Initial values are not applied to new customers created through the Vendor API v3.

• Lock fields to prevent accidental modifications, indicated by a lock icon on customer management pages

The following shows an example of a customer license:

apiVersion: kots.io/v1beta1
kind: License
metadata:
  name: customertest
spec:
  appSlug: gitea
  channelID: 2iy68JBTkvUqamgD...
  channelName: Beta
  channels:
  - channelID: 2iy68JBTkvUqamgD...
    channelName: Beta
    channelSlug: beta
    endpoint: https://replicated.app
    isDefault: true
    isSemverRequired: true
    replicatedProxyDomain: proxy.replicated.com
  customerEmail: example@replicated.com
  customerName: Customer Test
  endpoint: https://replicated.app
  entitlements:
    expires_at:
      description: License Expiration
      signature: {}
      title: Expiration
      value: ""
      valueType: String
  isAirgapSupported: true
  isEmbeddedClusterDownloadEnabled: true
  isKotsInstallEnabled: true
  isSemverRequired: true
  isSupportBundleUploadSupported: true
  licenseID: 2sY6ZC2J9sO2...
  licenseSequence: 4
  licenseType: prod
  replicatedProxyDomain: proxy.replicated.com
  signature: eyJsaWNlbnNlRGF...

Built-In License Field Names

This section lists the built-in fields that are included in customer licenses for applications distributed with Replicated.

note

The built-in license fields are reserved field names.

General License Fields

Field Name	Description
appSlug	The unique application slug that the customer is associated with. This value never changes.
channelID	The ID of the channel where the customer is assigned. When the customer's assigned channel changes, the latest release from that channel will be downloaded on the next update check.
channelName	The name of the channel where the customer is assigned. When the customer's assigned channel changes, the latest release from that channel will be downloaded on the next update check.
licenseID, licenseId	Unique ID for the installed license. This value never changes.
customerEmail	The customer email address.
endpoint	For applications installed with a Replicated installer (KOTS, kURL, Embedded Cluster), this is the endpoint that the KOTS Admin Console uses to synchronize the licenses and download updates. This is typically https://replicated.app.
entitlementValues	Includes both the built-in expires_at field and any custom license fields. For more information about adding custom license fields, see Manage Customer License Fields.
expires_at	Defines the expiration date for the license. The date is encoded in ISO 8601 format (2026-01-23T00:00:00Z) and is set to midnight UTC at the beginning of the calendar day (00:00:00) on the date selected. If a license does not expire, this field is missing. For information about the default behavior when a license expires, see License Expiration Handling in About Customers.
licenseSequence	Every time a license is updated, its sequence number is incremented. This value represents the license sequence that the client currently has.
customerName	The name of the customer.
signature	The base64-encoded license signature. This value will change when the license is updated.
licenseType	A string value that describes the type of the license, which is one of the following: paid, trial, dev, single-tenant-vendor-managed or community. For more information about license types, see Managing License Type.

Install Types

The table below describes the built-in license fields related to the supported install type(s). For more information, see Manage Install Types for a License.

Field Name	Description
isEmbeddedClusterDownloadEnabled	If a license supports installation with Replicated Embedded Cluster, this field is set to true or missing. If Embedded Cluster installations are not supported, this field is false. This field requires that the vendor has the Embedded Cluster entitlement and that the release at the head of the channel includes an Embedded Cluster Config custom resource. This field also requires that the "Install Types" feature is enabled for your Vendor Portal team. Reach out to your Replicated account representative to get access.
isHelmInstallEnabled	If a license supports Helm installations, this field is set to true or missing. If Helm installations are not supported, this field is set to false. This field requires that the vendor packages the application as Helm charts and, optionally, Replicated custom resources. This field requires that the "Install Types" feature is enabled for your Vendor Portal team. Reach out to your Replicated account representative to get access.
isKotsInstallEnabled	If a license supports installation with Replicated KOTS, this field is set to true. If KOTS installations are not supported, this field is either false or missing. This field requires that the vendor has the KOTS entitlement.
isKurlInstallEnabled	If a license supports installation with Replicated kURL, this field is set to true or missing. If kURL installations are not supported, this field is false. This field requires that the vendor has the kURL entitlement and a promoted kURL installer spec. This field also requires that the "Install Types" feature is enabled for your Vendor Portal team. Reach out to your Replicated account representative to get access.

Install Options

The table below describes the built-in license fields related to install options.

Field Name	Description
isAirgapSupported	If a license supports air gap installations with the Replicated installers (KOTS, kURL, Embedded Cluster), then this field is set to true. If Replicated installer air gap installations are not supported, this field is missing. When you enable this field for a license, the license.yaml file will have license metadata embedded in it and must be re-downloaded.
isEmbeddedClusterMultiNodeEnabled	If a license supports multi-node installations with Embedded Cluster, this field is set to true. If a license does not support multi-node installations, this field is either missing or false. By default, isEmbeddedClusterMultiNodeEnabled is true. When isEmbeddedClusterMultiNodeEnabled is missing or false, the Configure the cluster page is hidden from the Embedded Cluster installation flow in the Admin Console. Additionally, the join command is not available and the option to add nodes is removed from the Admin Console Cluster management page.
isHelmAirgapEnabled	If a license supports Helm air gap installations, then this field is set to true or missing. If Helm air gap is not supported, this field is missing. When you enable this feature, the license.yaml file will have license metadata embedded in it and must be re-downloaded. This field requires that the "Install Types" feature is enabled for your Vendor Portal team. Reach out to your Replicated account representative to get access.

Admin Console Feature Options

The table below describes the built-in license fields related to the Admin Console feature options. The Admin Console feature options apply only to licenses that support installation with the Replicated installers (KOTS, kURL, Embedded Cluster).

Field Name	Description
isDisasterRecoverySupported	If a license supports the Embedded Cluster disaster recovery feature, this field is set to true. If a license does not support disaster recovery for Embedded Cluster, this field is either missing or false. Note: Embedded Cluster Disaster Recovery is in Alpha. To get access to this feature, reach out to Alex Parker at alexp@replicated.com. For more information, see Disaster Recovery for Embedded Cluster.
isGeoaxisSupported	(kURL Only) If a license supports integration with GeoAxis, this field is set to true. If GeoAxis is not supported, this field is either false or missing. Note: This field requires that the vendor has the GeoAxis entitlement. It also requires that the vendor has access to the Identity Service entitlement.
isGitOpsSupported	important KOTS Auto-GitOps is a legacy feature and is not recommended for use. For modern enterprise customers that prefer software deployment processes that use CI/CD pipelines, Replicated recommends the Helm CLI installation method, which is more commonly used in these types of enterprise environments. If a license supports the KOTS AutoGitOps workflow in the Admin Console, this field is set to true. If Auto-GitOps is not supported, this field is either false or missing. See KOTS Auto-GitOps Workflow.
isIdentityServiceSupported	If a license supports identity-service enablement for the Admin Console, this field is set to true. If identity service is not supported, this field is either false or missing. Note: This field requires that the vendor have access to the Identity Service entitlement.
isSemverRequired	If set to true, this field requires that the Admin Console orders releases according to Semantic Versioning. This field is controlled at the channel level. For more information about enabling Semantic Versioning on a channel, see Semantic Versioning in About Releases.
isSnapshotSupported	If a license supports the snapshots backup and restore feature, this field is set to true. If a license does not support snapshots, this field is either missing or false. Note: This field requires that the vendor have access to the Snapshots entitlement.
isSupportBundleUploadSupported	If a license supports uploading a support bundle in the Admin Console, this field is set to true. If a license does not support uploading a support bundle, this field is either missing or false.

Custom License Fields

Custom license fields allow you to add application-specific entitlements and configuration data to customer licenses beyond the built-in fields described above.

Creating Custom Fields

When creating custom fields, you can specify:

• Field name (immutable reference identifier - use lowercase with underscores, e.g., max_users, support_tier)
• Title (display name across Portal and Admin Console)
• Type (determines validation and UI widget)
• Default value (applied to all customers unless overridden)
• Required flag (enforces completion)
• Hidden option (conceals field from customers while keeping it visible to vendors)

For detailed instructions on creating and managing custom license fields, see Manage Customer License Fields.

Field Types Available

The following field types are available for custom license fields:

Type	Purpose	When to Use	Interface
Integer	Whole numbers	Capacity limits, quotas, counts (e.g., seats: 100)	Text field
String	Single-line text	Short identifiers, tier names, regions (e.g., tier: enterprise)	Text field
Text	Multi-line content	Long configurations, JSON data, descriptions	Text area
Boolean	True/false values	Feature flags, support options (e.g., premium_support: true)	Checkbox
Password	Masked text	API keys, tokens, credentials (masked in UI, cleartext in license)	Password field
Enum	Predefined options	Limited choices like tier levels or regions	Dropdown

Accessing Field Values in Your Application

Custom fields appear in the license YAML under spec.entitlements. Your application can read these values to enforce limits or configure behavior.

Example license YAML with custom fields:

apiVersion: kots.io/v1beta1
kind: License
spec:
  licenseID: "customer-123"
  customerName: "Acme Corp"
  entitlements:
    seats:
      title: Maximum Users
      value: 100
      valueType: Integer
    tier:
      title: Support Tier
      value: "enterprise"
      valueType: String
    premium_support:
      title: Premium Support Enabled
      value: true
      valueType: Boolean

Your application can parse this YAML to access entitlement values programmatically using the Replicated SDK or KOTS template functions.

Managing Fields via API

Custom license fields can also be created and managed through the Vendor API v3. This enables automation and integration with your existing systems. For more information, see the Vendor API v3 documentation.

Important Constraints

note

The maximum size for a license field value is 64KB.

This limit applies to the data capacity of individual field values.

Field Deletion

Deleting a custom field removes associated values from licenses system-wide. When deleting a field, you have the option to preserve non-default values as hidden records for potential future recovery using the "Preserve License Values" option.

Customer-Specific Configuration

Individual customer values override defaults when administrators navigate to the customer management page and populate custom fields in the designated section. This allows you to configure license entitlements on a per-customer basis.