DOC-3226: Update license key documentation for TinyMCE 8, clarifying API key usage, T8LK prefix requirements, and adding common error messages with solutions.

kemister85 · kemister85 · commit 7d83819da292 · 2025-07-09T14:59:31.000+10:00
diff --git a/modules/ROOT/pages/license-key.adoc b/modules/ROOT/pages/license-key.adoc
@@ -154,7 +154,7 @@ The GPLv2+ license was chosen to provide the best compatibility with existing GP
 
 === What is the difference between a license key and the API key?
 
-The **API key** is used when loading TinyMCE from the {cloudname}. The license key is used to declare the license terms when self-hosting {productname}.
+The **API key** is used when loading {productname} from the {cloudname}. The license key is used to declare the license terms when self-hosting {productname}.
 
 === Who needs to get a license key?
 
@@ -190,19 +190,19 @@ In addition to the editor being readonly, a console log warning message and/or e
 
 The license key ensures compliance with {productname} licensing terms. It's part of our efforts to refine the license key system and may have additional functionalities in the future.
 
-=== How do I obtain a TinyMCE 8 license key?
+=== How do I obtain a {productname} 8 license key?
 
-To obtain a new TinyMCE 8 license key (T8LK-prefixed):
+To obtain a new {productname} 8 license key (T8LK-prefixed):
 
 * *Existing customers*: Contact your account manager or visit link:https://www.tiny.cloud/my-account[Tiny Cloud Account] to upgrade your subscription.
 * *New customers*: Visit link:https://www.tiny.cloud/pricing[Tiny Cloud Pricing] to purchase a new license.
 
 [IMPORTANT]
 ====
-Existing TinyMCE 7 license keys cannot be modified to work with TinyMCE 8 by adding the T8LK prefix. A new TinyMCE 8 license must be obtained through the proper channels listed above.
+Existing {productname} 7 license keys cannot be modified to work with {productname} 8 by adding the T8LK prefix. A new {productname} 8 license must be obtained through the proper channels listed above.
 ====
 
-=== I'm upgrading from {productname} 7 - how do I get a {productname} 8 license key?
+=== If im upgrading from TinyMCE 7 how do I get a TinyMCE 8 license key?
 
 If you are using {cloudname} (cloud-hosted):
 
@@ -218,7 +218,7 @@ If you are an existing {productname} 7 self-hosted customer upgrading to {produc
 
 [NOTE]
 ====
-Your existing {productname} 7 license key will continue to work with TinyMCE 7 self-hosted installations. But, you will require a separate T8LK-prefixed license key for {productname} 8 editor instances for self-hosted installations.
+Your existing {productname} 7 license key will continue to work with {productname} 7 self-hosted installations. But, you will require a separate T8LK-prefixed license key for {productname} 8 editor instances for self-hosted installations.
 ====
 
 === How can I get further assistance?
@@ -229,6 +229,107 @@ For any licensing or technical support questions, see our available options on t
 
 For licensing or technical support:
 * API key issues: Visit link:https://www.tiny.cloud/my-account[Tiny Cloud Account]
-* License key issues: Contact your account manager
+* License key issues: Visit link:https://www.tiny.cloud/my-account[Tiny Cloud Account] or contact your account manager
 * Technical support: Visit link:https://support.tiny.cloud[Support Portal]
-* Documentation: See link:https://www.tiny.cloud/docs/tinymce/latest/[TinyMCE Docs]
+* Documentation: See link:https://www.tiny.cloud/docs/tinymce/latest/[{productname} Docs]
+
+== License Key Error Messages
+
+The following table lists common license key error messages that may appear in the console or editor, along with their descriptions and solutions:
+
+[cols="1,2,2,2", options="header"]
+|===
+| Error Type | Console Message | Editor Notifications | Solution
+
+| xref:invalid-license-key[Invalid license key (General)]
+| The editor is disabled because the license key provided is invalid [+${errorType}+]
+| The editor is disabled because the license key provided is invalid.
+a| * Verify that the license key is correctly copied from your link:https://www.tiny.cloud/my-account[Tiny Cloud Account]
+* Ensure there are no extra spaces or characters in the key
+* Check if the key matches your deployment type (Cloud vs Self-hosted)
+
+| xref:hard-expired[Hard expired]
+| The editor is disabled because the license key has expired and is no longer valid
+| The editor is disabled because the license key has expired and is no longer valid.
+a| * Visit link:https://www.tiny.cloud/my-account[Tiny Cloud Account] to obtain a new license key
+* Update your configuration with the new key
+* Visit the link:https://support.tiny.cloud[Support Portal] if you believe your license should still be valid
+
+| xref:soft-expired[Soft expired]
+| The editor will be disabled in the near future because the license key has expired
+| The editor will be disabled in the near future because the license key has expired.
+a| * Visit link:https://www.tiny.cloud/my-account[Tiny Cloud Account] to obtain a new license key
+* Update your configuration before the grace period ends
+* Visit the link:https://support.tiny.cloud[Support Portal] if you need assistance with license renewal
+
+| xref:invalid-editor-version[Invalid editor version]
+| The editor is disabled because the license key is not valid with this version of {productname}
+| The editor is disabled because the license key is not valid with this version of {productname}.
+a| * Verify that your {productname} version matches the license key version
+* Update either your {productname} version or obtain a new license key
+* For version-locked keys, ensure you're using the correct patch version
+
+| xref:no-license-key[No license key]
+| The editor is disabled because a {productname} license key has not been provided. Provide a valid license key or add license_key: 'gpl' to the init config to agree to the open source license terms.
+| The editor is disabled because a {productname} license key has not been provided.
+a| * Add the `license_key` parameter to your {productname} configuration
+* For GPL usage, set `license_key: 'gpl'`
+* For commercial usage, enter your valid commercial license key
+
+| xref:invalid-plugin[Invalid plugin]
+| The "+${pluginCode}+" plugin requires a valid {productname} license key
+| _No editor message_
+a| * Verify that your license includes access to the premium plugin
+* Check if your license key is valid and not expired
+* Visit the link:https://support.tiny.cloud[Support Portal] if you believe you should have access to this plugin
+
+| xref:online-api-key-error-fallback[Online API Key Error (5xx - Fallback)]
+| The API key could not be validated by the API key validation server [type: +${errorType}${statusMsg}+]. Attempting fallback to provided license key.
+| The editor is disabled because the API key could not be validated by the API key validation server.
+a| * Check your internet connection
+* Verify your firewall settings allow access to the validation server
+* The editor will attempt to use the provided license key as fallback
+
+| xref:online-api-key-error-disable[Online API Key Error (4xx - Disable)]
+| The editor is disabled because the API key could not be validated by the API key validation server [type: +${errorType}${statusMsg}+]
+| The editor is disabled because the API key could not be validated by the API key validation server.
+a| * Verify that your API key is valid
+* Check if your subscription is active
+* Visit the link:https://support.tiny.cloud[Support Portal] if the issue persists
+|===
+
+=== Detailed Error Descriptions
+
+[[invalid-license-key]]
+==== Invalid license key (General)
+The provided license key is not recognized as a valid {productname} license key. This can occur if the key is malformed, expired, or doesn't match your deployment type. For self-hosted installations, ensure you're using a valid T8LK-prefixed license key. Visit the link:https://www.tiny.cloud/my-account[Tiny Cloud Account] to verify your license key.
+
+[[hard-expired]]
+==== Hard expired
+The license key has reached its expiration date and is no longer valid for use. The editor will be disabled until a new valid license key is provided. For time-based keys, refer to the <<License Key Types>> section. To renew your license, visit link:https://www.tiny.cloud/pricing[Tiny Cloud Pricing] or contact your account manager.
+
+[[soft-expired]]
+==== Soft expired
+The license key has reached its initial expiration date but is still within the grace period. The editor will continue to function but will be disabled when the grace period ends. See the <<License States>> section for more information about grace periods. Contact your account manager or visit link:https://www.tiny.cloud/my-account[Tiny Cloud Account] to renew your license before the grace period expires.
+
+[[invalid-editor-version]]
+==== Invalid editor version
+The license key is not compatible with the current version of {productname}. This typically occurs with version-locked keys when using a different patch version. Visit link:https://www.tiny.cloud/docs/tinymce/latest/[TinyMCE Documentation] to check your editor version. Review the <<License Key Types>> section about version-locked keys. If you're upgrading from {productname} 7, visit link:https://www.tiny.cloud/my-account[Tiny Cloud Account] to obtain a new license key or see <<If im upgrading from TinyMCE 7 how do I get a TinyMCE 8 license key?>> for guidance. For new licenses, visit link:https://www.tiny.cloud/pricing[Tiny Cloud Pricing].
+
+[[no-license-key]]
+==== No license key
+No license key has been provided in the {productname} configuration. For self-hosted installations, you must either provide a valid commercial license key or explicitly opt into GPL usage. See the <<Setting up the Commercial License Key Manager>> section for implementation details and the "<<What does the GPL license mean?>>" section for GPL licensing information.
+
+[[invalid-plugin]]
+==== Invalid plugin
+The attempted use of a premium plugin without a valid commercial license key. This occurs when trying to use premium features with a GPL license or an invalid commercial license. Review your subscription details in your link:https://www.tiny.cloud/my-account[Tiny Cloud Account] to verify plugin access. See the <<License Types and Deployment Options>> section for more information about license types and plugin access.
+
+[[online-api-key-error-fallback]]
+==== Online API Key Error (5xx - Fallback)
+A server-side error occurred while validating the API key. The editor will attempt to use the provided license key as a fallback mechanism. This typically occurs in hybrid deployments - see the <<Deployment Types>> section for proper configuration. If the issue persists, visit link:https://support.tiny.cloud[Support Portal] for assistance.
+
+[[online-api-key-error-disable]]
+==== Online API Key Error (4xx - Disable)
+The API key validation failed due to an invalid key or inactive subscription. The editor will be disabled until a valid API key is provided. For API key issues, visit link:https://www.tiny.cloud/my-account[Tiny Cloud Account] or see the "<<What is the difference between a license key and the API key?>>" section for clarification.
+
+For additional assistance, visit our link:https://support.tiny.cloud[Support Portal] or contact your link:https://www.tiny.cloud/my-account[Tiny Cloud Account] manager.
